情境資料與同意

本頁譯自英文。如兩者有出入，以英文頁面為準。閱讀英文頁面

你的 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 以要求較少的片段，被你移除的那些會立即停止。
如果你編輯 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 函式庫