情境資料同同意

呢頁係由英文翻譯過嚟嘅。如果兩個版本有出入，以英文頁為準。睇英文頁

你個 App 只可以透過情境資料片段知道學習者嘅嘢。每個片段都係一份欄位固定嘅細記錄。你嘅 manifest 列出佢要求嘅片段，學習者安裝你個 App 嗰陣逐個同意，而 Lingara 淨係會喺兩樣都仲成立嘅時候先傳一個片段。

片段

片段	欄位	入面有乜
`languages`	`source_lang`	學習者用嚟學嘢嘅語言，用語言標記表示，例如 `en`。
	`target_lang`	佢哋學緊嘅語言。
	`level`	佢哋喺嗰種語言嘅等級，由 1 到 9，前提係佢哋有設定。
`plan_summary`	`plan_id`	佢哋最新課程計畫嘅 id，用嚟分辨唔同嘅計畫。你個 App 唔可以用佢攞個計畫，因為你個 App 嘅權杖讀嘅係你自己個帳戶，唔係學習者嘅。
	`title`	個計畫產生出嚟嘅標題，最多 120 個字元，前提係佢有標題。
	`target_lang`	個計畫教嘅語言。
	`set_count`	個計畫有幾多組，最多 200。
	`sets_completed`	學習者做完咗其中幾多組。
`review_due`	`due`	而家有幾多張閃卡到期，最多 100000。
	`learned`	佢哋學識咗幾多個詞，最多 100000。
`tutor_topic`	`topic`	佢哋最新導師對話講緊乜，由 1 到 120 個字元。佢嚟自一個計畫嘅標題或者佢哋身處嘅畫面，永遠唔會嚟自佢哋自己講嘅說話。

冇片段會帶嘅嘢

冇任何片段會帶電郵地址、名、用戶 id，或者任何學習者打過嘅嘢。你個 App 由請求嘅 subject 知道個學習者係邊個，呢個係一個穩定嘅值，每個 App 收到嘅都唔同。你個 App 嘅權杖讀嘅係你自己個帳戶，永遠唔會係學習者嘅，所以片段就係你個 App 對佢哋所知嘅全部。

同意

學習者安裝你個 App 嗰陣，會逐個片段同意。想改佢哋同意咗嘅嘢，佢哋要解除安裝你個 App 再重新安裝。
如果你改 manifest 要求少啲片段，你拎走咗嗰啲會即刻停。
如果你改佢要求多啲片段，新嘅片段喺學習者重新安裝之前唔會去到任何學習者度。
Lingara 每個請求都會再檢查一次同意，學習者冇同意嘅、或者你個 manifest 已經冇再要求嘅片段，都會被丟棄。唔啱佢記錄格式嘅片段都會被丟棄，但永遠唔會丟棄成個請求。

下面個範例用佢收到嘅片段砌出佢嗰行字，冇調用任何 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 函式庫