Instalação do Web SDK

Status em produção e ativação

A coleta do Web SDK está implantada em produção, em modo shadow (status em produção). A operação dela de ponta a ponta a partir de uma página de cliente ainda está sendo medida; os primeiros números de latência de navegadores reais, em uma aplicação, estão na página de coleta. Prepare o frontend e o backend juntos; a coleta só é aceita pelo domínio de coleta ativo da sua aplicação, com o pacote aprovado e os insumos emitidos. Um contexto indisponível vira null; ele não deve interromper o login normal do seu produto. Veja a entrega da implementação.

Seus insumos de instalação verificados

• A chave pública da aplicação (pub_app_…). Ela é um localizador, não um segredo.
• O domínio de coleta ativo, por exemplo https://collect.yourcompany.com.
• A versão aprovada do pacote privado fingertrackid-sdk-web.tgz com os digests SHA-256 e SHA-512 dele. Baixe o pacote e veja os dois digests no console, com sessão iniciada na sua empresa: no Início, etapa Configuração do SDK, ou em Integração e saúde, cartão Pacote do SDK Web. Seu papel precisa ter permissão para ler a integração (administrador da empresa, gestor de integração ou auditor).

O SDK não é publicado em nenhum registro público do npm. Não instale um pacote de um registro público só porque o nome dele coincide.

Instalação: pacote privado

Inclua o arquivo aprovado no bundle do seu frontend. O console mostra os digests que o FingerTrackID registrou para a versão aprovada; ele não os calcula a partir do arquivo que você recebeu, e se recusa a salvar um download que não confere com o SHA-256. Mesmo assim, verifique os dois digests na sua própria máquina antes de instalar; um digest encontrado ao lado de um arquivo não confiável não é aprovação. Se o console disser que o pacote ainda não está disponível, fale com o suporte do FingerTrackID.

Cada digest impresso precisa ser igual ao mostrado no console. O PowerShell imprime o digest em maiúsculas; compare sem diferenciar maiúsculas de minúsculas. O console oferece os mesmos comandos para copiar, para os dois sistemas. O pacote declara seus tipos TypeScript.

Importe e inicialize em código de navegador, não durante a renderização no servidor. Carregue exatamente uma cópia; mantenha um cliente para o documento atual do navegador e o ciclo de vida da conta, num módulo que sobreviva aos componentes da sua página (a receita de coleta faz isso). Faça commit do lockfile e mantenha o arquivo aprovado no seu processo de dependências. No logout ou na troca de conta, feche este cliente e descarte os handles de ação dele antes de inicializar outro.

Seu bundler pode minificar o pacote de novo com as suas configurações de produção. Desde a 0.2.1, as verificações de navegador do SDK continuam medindo sob opções de minificador que tratam métodos nativos como livres de efeitos colaterais, como a compress.unsafe do terser; com a 0.2.0, um build assim as removia (veja as notas de versão). Antes de cada versão, o pacote é verificado reminificado pelo terser e pelo SWC com unsafe, unsafe_methods, pure_getters, passes: 3 e toplevel, e com as demais opções unsafe_* que mantêm correto o código comum.

Três opções de compressão reescrevem aritmética comum e verificações de tipo. Medido no SDK 0.2.0, cada uma delas, sozinha, quebra o SDK: a abertura da sessão já falha, com TRANSPORT_ERROR ou INVALID_RESPONSE, e nenhuma coleta chega ao FingerTrackID. A mesma medição na 0.3.0 ainda está pendente. Mantenha-as desligadas para o pacote do SDK:

Minificador	Opção que quebra o SDK
terser	compress.unsafe_math, compress.booleans_as_integers
SWC	compress.unsafe_math, compress.unsafe_hoist_static_method_alias

Se o seu build liga uma delas, exclua o pacote do SDK dessa minificação ou desligue a opção e, depois, confira no painel de rede do navegador se a abertura da sessão e a coleta se completam.

macOS ou Linux

shasum -a 256 fingertrackid-sdk-web.tgz
shasum -a 512 fingertrackid-sdk-web.tgz
npm install --save-exact --ignore-scripts ./fingertrackid-sdk-web.tgz

Windows

Get-FileHash -Algorithm SHA256 .\fingertrackid-sdk-web.tgz
Get-FileHash -Algorithm SHA512 .\fingertrackid-sdk-web.tgz
npm install --save-exact --ignore-scripts ./fingertrackid-sdk-web.tgz

import { initializeSdk } from '@ftid/sdk-web'

let sdk = null
try {
  sdk = initializeSdk({
    publicKey: 'REPLACE_WITH_ISSUED_PUBLIC_APPLICATION_KEY',
    collectionOrigin: 'https://collect.customer.example',
  })
} catch {
  // Optional collection must not interrupt the customer's normal business action.
}

Sem instalação por script

O pacote privado incluído no bundle do seu frontend é a única forma de entrega. O FingerTrackID não serve o SDK como script: a distribuição por script não está habilitada, e uma origem de coleta ativa não hospeda nenhum arquivo do SDK. Não carregue o SDK de uma URL nem de uma CDN pública.

initializeSdk

• Recebe exatamente duas chaves: publicKey (formato pub_app_…) e collectionOrigin (uma origem HTTPS sem caminho, query, fragmento, credenciais nem porta padrão explícita).
• É síncrona e não faz nenhuma requisição de rede.
• Na mesma página, a mesma configuração devolve o mesmo cliente enquanto ele estiver aberto; uma configuração diferente lança CONFIGURATION_CONFLICT.
• Uma configuração inválida lança INVALID_CONFIGURATION; um navegador sem os recursos exigidos lança UNSUPPORTED_RUNTIME. Todas as outras chamadas do SDK informam falhas no próprio resultado em vez de lançar exceção, exceto createEvent (o que lança exceção).

O SDK exige uma página segura (HTTPS), Fetch, aleatoriedade criptográfica nativa e um relógio monotônico. Confirme a matriz de navegadores efetivamente qualificada com a sua versão do SDK; recursos do navegador, sozinhos, não são evidência de compatibilidade com todo navegador/versão.

A CSP do seu site

Acrescente a origem de coleta ativa exata ao seu connect-src existente. O SDK é incluído no bundle do seu próprio código, então não precisa de nenhuma entrada em script-src.

Isto é um fragmento, não uma CSP completa. O SDK não precisa de unsafe-inline, unsafe-eval, curingas de host nem handlers inline. Desde o SDK 0.1.1, ele não gera código em tempo de execução, então uma CSP sem unsafe-eval não produz nenhum relatório de violação por causa dele. (O SDK 0.1.0 produzia uma violação inofensiva de eval em script-src quando o módulo dele era avaliado pela primeira vez.) As chamadas do seu backend à API de avaliação, https://api.fingertrackid.com, são servidor a servidor e não entram nesta lista do navegador; o navegador só fala com o seu domínio de coleta.

connect-src 'self' https://collect.customer.example;

Rastreamento e outros cabeçalhos de requisição

O domínio de coleta aceita exatamente os cabeçalhos de requisição que o SDK envia: Content-Type, mais X-Capability-Token nas requisições de coleta e de contexto do evento, ou X-SDK-Session-Token na renovação e no encerramento. O navegador anuncia qualquer outro cabeçalho no preflight de CORS, e o domínio de coleta recusa esse preflight (400, sem aprovação de CORS). O navegador então esconde a resposta e a requisição do SDK falha: toda chamada devolve UNAVAILABLE com o motivo TRANSPORT_ERROR, e nenhuma coleta chega ao FingerTrackID.

Uma instrumentação de página que acrescenta cabeçalhos de rastreamento às requisições fetch de saída causa exatamente isso quando um dos padrões de URL dela também casa com a sua origem de coleta, por exemplo um padrão para todo subdomínio do seu domínio. Mantenha a origem de coleta fora da propagação de rastreamento:

Ferramenta	Opção	O que conferir
SDKs de navegador do Sentry	tracePropagationTargets	Uma entrada do tipo string casa com qualquer URL que a contenha, então 'yourcompany.com' também casa com https://collect.yourcompany.com. Liste as origens das suas próprias APIs com padrões ancorados, como /^https:\/\/api\.yourcompany\.com\//
Datadog Browser RUM	allowedTracingUrls	Nenhuma entrada, expressão regular ou função casa com a origem de coleta
OpenTelemetry FetchInstrumentation	propagateTraceHeaderCorsUrls	Nenhuma entrada casa com a origem de coleta
Qualquer outro wrapper de fetch ou cliente HTTP que acrescente cabeçalhos	—	Ele não acrescenta nada às requisições cuja URL começa com a sua origem de coleta

Para conferir, abra o painel de rede do navegador numa página que faz coleta: cada requisição OPTIONS ao seu domínio de coleta lista em Access-Control-Request-Headers só content-type (abertura da sessão) ou content-type, x-capability-token (coleta e contexto do evento), e é respondida com 204.

Atualização do SDK

A coleta da sua aplicação aceita uma versão do SDK por vez, e uma requisição de outra versão é recusada com AUTHENTICATION_FAILED. Instale a versão que o console oferece. Se a sua aplicação já coleta com uma versão anterior, fale com o suporte do FingerTrackID antes de implantar um pacote novo: o FingerTrackID passa a aplicação para a nova versão e você implanta o pacote novo ao mesmo tempo, porque a partir daí a versão anterior é recusada. O que mudou da 0.1.1 para a 0.2.0 para o seu código está na página de coleta.

A partir da 0.3.0, um número de versão identifica um único pacote para sempre: um número publicado nunca volta com outro arquivo. Qualquer mudança posterior, mesmo de um único byte, recebe um número novo: um patch quando nada muda na API nem no comportamento, uma versão minor (na 0.x) quando algo é acrescentado ou se comporta de outro jeito, com todo item que quebra compatibilidade listado abaixo. Quando o console oferecer uma versão nova, leia as notas de versão dela antes de instalá-la.

Notas de versão

• 0.3.0.
  • O que muda. Um export novo, createActionContextHelper(client, options?), com seus tipos (SdkActionContextHelper, SdkActionContext e os demais na página de coleta): ele executa o ciclo de vida por você, com prefetch() na primeira intenção de um formulário, um take() por ação de negócio e close(). O relógio de credenciais do SDK agora conta o tempo em que o dispositivo ficou em suspensão. Todos os exports, tipos, requisições e tempos da 0.2.x continuam iguais.
  • O que quebra. Nada na API. Depois que o dispositivo entra em suspensão, o cliente deixa de usar uma credencial, uma sessão ou um token em cache que expirou durante a suspensão: um token em cache que passou do seu expiresAt responde EVENT_CONTEXT_EXPIRED, e a próxima coleta depois de mais de 30 minutos em suspensão abre uma sessão nova em vez de reaproveitar a antiga. A coleta da sua aplicação aceita uma versão do SDK por vez: assim que o FingerTrackID a passa para a 0.3.0, um navegador que ainda roda a 0.2.1 é recusado com AUTHENTICATION_FAILED.
  • Migração. Fale com o suporte para agendar a mudança. Baixe a 0.3.0 no console, verifique os dois digests e instale-a com npm install --save-exact --ignore-scripts. Seu código de página da 0.2.x roda sem mudança; trocá-lo pela receita é recomendado e pode ficar para depois. Gere o build do seu frontend e deixe-o preparado, e implante-o logo depois que o FingerTrackID confirmar a mudança. Depois, entre uma vez e confira se o login chegou ao seu backend com um token.
• 0.2.1. Nada muda para o seu código: a API, o ciclo de vida, as requisições e os tempos são os da 0.2.0. Ela corrige a 0.2.0 em bundlers que minificam o pacote com opções que tratam métodos nativos como livres de efeitos colaterais (por exemplo a compress.unsafe do terser): num build assim, a 0.2.0 perdia as verificações do motor JavaScript, e por isso os sinais de privacidade do navegador e de janela privada de todo acesso voltavam como não avaliados. A 0.2.1 os mantém medindo sob o terser e o SWC com essas opções. Se a sua aplicação coleta com a 0.2.0, fale com o suporte para passá-la para a 0.2.1 como descrito acima.
• 0.2.0. prepare(), uma sessão nova do SDK para cada nova coleta, prazos do cliente acima dos orçamentos do servidor com novas tentativas dentro da mesma chamada, e reaproveitamento do preflight de CORS. O que ela muda para o seu código está na página de coleta.

Próximo passo: colete e obtenha o contexto do evento.