Contexto e consentimento

Esta página é uma tradução do inglês. Se as duas diferirem, a página em inglês é a correta. Ler a página em inglês

A sua aplicação só fica a saber algo sobre um aprendente através de fatias de contexto. Cada fatia é um pequeno registo com campos fixos. O seu manifest lista as fatias que pede, o aprendente aceita cada uma quando instala a sua aplicação, e o Lingara só envia uma fatia enquanto ambas as condições se mantiverem.

As fatias

Fatia	Campo	O que contém
`languages`	`source_lang`	O idioma a partir do qual o aprendente estuda, como etiqueta de idioma, por exemplo `en`.
	`target_lang`	O idioma que está a aprender.
	`level`	O seu nível nesse idioma, de 1 a 9, quando definiu um.
`plan_summary`	`plan_id`	O id do seu plano de lição mais recente, que distingue um plano de outro. A sua aplicação não pode obter o plano com ele, porque o token da sua aplicação lê a sua própria conta, não a do aprendente.
	`title`	O título gerado do plano, com no máximo 120 caracteres, quando o tem.
	`target_lang`	O idioma que o plano ensina.
	`set_count`	Quantos conjuntos o plano tem, no máximo 200.
	`sets_completed`	Quantos desses conjuntos o aprendente terminou.
`review_due`	`due`	Quantos cartões estão pendentes de revisão agora, no máximo 100000.
	`learned`	Quantas palavras aprendeu, no máximo 100000.
`tutor_topic`	`topic`	O assunto da sua conversa mais recente com o tutor, de 1 a 120 caracteres. Vem do título de um plano ou do ecrã em que está, nunca das suas próprias palavras.

O que nenhuma fatia transporta

Nenhuma fatia transporta um endereço de email, um nome, um id de utilizador ou qualquer coisa que o aprendente tenha escrito. A sua aplicação fica a saber quem é o aprendente pelo subject do pedido, um valor estável que é diferente para cada aplicação. O token da sua aplicação lê a sua própria conta, nunca a do aprendente, por isso as fatias são tudo o que a sua aplicação sabe sobre ele.

Consentimento

O aprendente aceita cada fatia quando instala a sua aplicação. Para alterar o que aceitou, desinstala a sua aplicação e volta a instalá-la.
Se editar o seu manifest para pedir menos fatias, as que retirou param de imediato.
Se o editar para pedir mais, as novas fatias não chegam a nenhum aprendente até que este reinstale a aplicação.
O Lingara volta a verificar o consentimento em cada pedido e descarta qualquer fatia que o aprendente não aceitou ou que o seu manifest já não pede. Uma fatia que não encaixe no seu registo também é descartada, nunca o pedido inteiro.

O exemplo abaixo constrói a sua linha a partir das fatias que recebeu e não chama nenhuma 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;
}

Ver também

Bibliotecas da API Lingara