上下文与同意

本页译自英文。如两者有出入，以英文页面为准。阅读英文页面

你的应用只能通过上下文切片了解学习者。每个切片都是一条字段固定的小记录。你的清单列出它要求的切片，学习者在安装你的应用时逐一同意，而 Lingara 只在这两者都仍然成立时才发送某个切片。

切片

切片	字段	内容
`languages`	`source_lang`	学习者学习时所用的语言，以语言标签表示，例如 `en`。
	`target_lang`	他们正在学习的语言。
	`level`	他们在该语言上的等级，从 1 到 9，前提是他们设置过。
`plan_summary`	`plan_id`	他们最新课程计划的 id，用于区分不同的计划。你的应用无法用它获取该计划，因为你的应用的令牌读取的是你自己的账户，而不是学习者的。
	`title`	该计划生成的标题，最多 120 个字符，前提是它有标题。
	`target_lang`	该计划所教的语言。
	`set_count`	该计划包含多少组，最多 200。
	`sets_completed`	学习者已完成其中多少组。
`review_due`	`due`	现在有多少张闪卡到期，最多 100000。
	`learned`	他们已学会多少个词，最多 100000。
`tutor_topic`	`topic`	他们最新导师对话的主题，1 到 120 个字符。它来自计划的标题或他们所在的页面，绝不来自他们自己的话。

任何切片都不携带的内容

任何切片都不携带电子邮件地址、姓名、用户 id 或学习者输入的任何内容。你的应用通过请求中的 subject 得知学习者是谁，这是一个稳定的值，对每个应用都不同。你的应用的令牌读取的是你自己的账户，绝不是学习者的，因此切片就是你的应用对他们所知的全部。

同意

学习者在安装你的应用时逐一同意每个切片。要更改他们同意的内容，他们需要卸载你的应用后重新安装。
如果你编辑清单以要求更少的切片，被你去掉的那些会立即停止。
如果你编辑清单以要求更多切片，新的切片在学习者重新安装之前不会到达任何学习者。
Lingara 在每个请求上都会再次检查同意，并丢弃学习者未同意的、或你的清单不再要求的任何切片。不符合其记录的切片也会被丢弃，而绝不会丢弃整个请求。

下面的示例用它获得的切片构建自己的那一行，不调用任何 API。

TypeScriptRustGoJavaKotlinRubyPHP

TypeScript

// The app's own client reads its owner's account, never the learner's. The
// slices are all a render knows about the learner.
function planLine(request: AppRenderRequest): string {
  let line = "";
  for (const slice of request.context) {
    // A slice is present only when the learner agreed to share it.
    if (slice.kind === "languages") line += `${slice.source_lang} → ${slice.target_lang}. `;
    if (slice.kind === "plan_summary") line += `${slice.sets_completed}/${slice.set_count} sets.`;
  }
  return line;
}

Rust

// The app's own client reads its owner's account, never the learner's. The
// slices are all a render knows about the learner.
/// The learner's target language and, when they shared their plan, its
/// `(sets_completed, set_count)`.
fn shared_plan(request: &AppRenderRequest) -> (String, Option<(u32, u32)>) {
    let (mut target_lang, mut progress) = (String::from("zh"), None);
    for slice in &request.context {
        match slice {
            ContextSlice::Languages(languages) => target_lang = languages.target_lang.clone(),
            ContextSlice::PlanSummary(summary) => progress = Some((summary.sets_completed, summary.set_count)),
            _ => {}
        }
    }
    (target_lang, progress)
}

// The app's own client reads its owner's account, never the learner's.
// The slices are all a render knows about the learner.
//
// Each slice is present only when the learner agreed to share it.
card := lingaraapps.NewCard().Heading("Your plan", 1)
for _, slice := range req.Context {
	switch s := slice.(type) {
	case lingaraapps.ContextSliceLanguages:
		card.Text(fmt.Sprintf("Learning %s from %s", s.TargetLang, s.SourceLang))
	case lingaraapps.ContextSlicePlanSummary:
		card.Text(fmt.Sprintf("%d of %d sets done", s.SetsCompleted, s.SetCount))
	}
}

Java

import com.getlingara.apps.Card;
import com.getlingara.apps.Reply;
import com.getlingara.apps.model.AppRenderRequest;
import com.getlingara.apps.model.ContextSlice;
import com.getlingara.apps.model.ContextSliceLanguages;
import com.getlingara.apps.model.ContextSlicePlanSummary;

// The app's own client reads its owner's account, never the learner's. The slices are all a
// render knows about the learner.
static Reply render(AppRenderRequest request) {
  Card.Builder card = Card.card();
  // A slice is present only when the learner agreed to share it; the context is read-only.
  for (ContextSlice slice : request.getContext()) {
    if (slice instanceof ContextSliceLanguages languages) {
      card.heading("Learning " + languages.targetLang(), 1);
    } else if (slice instanceof ContextSlicePlanSummary summary) {
      card.text(summary.setsCompleted() + " of " + summary.setCount() + " sets done");
    }
  }
  return card.heading("Today", 2).build();
}

Kotlin

import com.getlingara.apps.kotlin.Reply
import com.getlingara.apps.kotlin.card
import com.getlingara.apps.kotlin.model.AppRenderRequest
import com.getlingara.apps.kotlin.model.ContextSliceLanguages
import com.getlingara.apps.kotlin.model.ContextSlicePlanSummary

// The app's own client reads its owner's account, never the learner's. The slices are all a
// render knows about the learner.
fun renderWithContext(request: AppRenderRequest): Reply {
    // A slice is present only when the learner agreed to share it; the context is read-only.
    val languages = request.context.filterIsInstance<ContextSliceLanguages>().firstOrNull()
    val summary = request.context.filterIsInstance<ContextSlicePlanSummary>().firstOrNull()
    return card {
        heading("Learning ${languages?.targetLang ?: "today"}", 1)
        if (summary != null) {
            text("${summary.setsCompleted} of ${summary.setCount} sets done")
        }
    }
}

Ruby

# The app's own client reads its owner's account, never the learner's. The
# slices are all a render knows about the learner.
#
# A slice is present only when the learner agreed to share it.
request.context.filter_map do |slice|
  case slice
  in Lingara::Apps::ContextSliceLanguages(source_lang:, target_lang:)
    "#{source_lang} → #{target_lang}."
  in Lingara::Apps::ContextSlicePlanSummary(sets_completed:, set_count:)
    "#{sets_completed}/#{set_count} sets."
  else nil
  end
end.join(" ")

PHP

use Lingara\Apps\Generated\ContextSliceLanguages;
use Lingara\Apps\Generated\ContextSlicePlanSummary;

function planLine(AppRenderRequest $request): string
{
    // The app's own client reads its owner's account, never the learner's. The
    // slices are all a render knows about the learner.
    $line = '';
    // A slice is present only when the learner agreed to share it.
    foreach ($request->getContext() as $slice) {
        if ($slice instanceof ContextSliceLanguages) {
            $line .= "{$slice->sourceLang} → {$slice->targetLang}. ";
        } elseif ($slice instanceof ContextSlicePlanSummary) {
            $line .= "{$slice->setsCompleted}/{$slice->setCount} sets.";
        }
    }
    return $line;
}

另请参阅

Lingara API 库