@akross/artemis-ads-sdk 3.7.8 → 3.7.10

package/CHANGELOG.md

@@ -5,6 +5,37 @@ Todas as mudanças notáveis do projeto são documentadas neste arquivo.
 O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.0/),
 e este projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR/).
 
+## [3.7.10] - 2026-04-10
+
+### Corrigido
+
+- **PPID não aparecia nos relatórios do Google Ad Manager**: O `userId` era enviado como PPID diretamente ao GPT, mas o Google Ad Manager exige PPIDs com 32–150 caracteres. Como a maioria dos userIds internos tem menos de 32 chars, o GAM descartava silenciosamente o valor — sem erro, mas sem efeito em frequency capping, segmentação ou relatórios. Agora o SDK deriva o PPID via SHA-256 do userId (hex de 64 chars), garantindo conformidade com a faixa exigida.
+- **`saveConfig` persistia config sem defaults**: `AAManager.initialize` salvava o objeto de config original no localStorage em vez do objeto com defaults aplicados (`ConfigUtils.applyDefaults`). Campos como `timeout`, `proxyExternalScripts` e `enableGPTPpid` não ficavam persistidos quando o publisher não os setava explicitamente.
+
+### Adicionado
+
+- **SHA-256 puro-JS** (`src/utils/sha256.ts`): Implementação síncrona sem dependência de `crypto.subtle`, permitindo uso em ambientes HTTP (não apenas HTTPS). Validada contra vetores FIPS 180-4.
+- **`sdk.setPublisherProvidedId(ppid)`**: Escape hatch para publishers que já possuem um PPID canônico de 32–150 chars e preferem não usar o hash automático do SDK. Requer `enableGPTPpid: true`.
+- **Restauração de PPID no boot**: Ao inicializar o SDK com um userId já persistido de sessão anterior, o PPID é derivado e enviado ao GPT automaticamente — sem necessidade de nova chamada a `setUserId`.
+- **Logs de diagnóstico no fluxo de PPID**: `catch` silenciosos substituídos por `logger.warn` / `logger.debug`, facilitando troubleshooting em ambientes com `debug: true`.
+
+### Alterado
+
+- **Validação de PPID**: Limite mínimo de tamanho ajustado de 1 para 32 caracteres, alinhado à exigência real do Google Ad Manager.
+- **`GPTPublisherProvidedId.ts`**: Toda a lógica de derivação, persistência e envio de PPID centralizada neste utilitário. `AAManager` ficou como fachada fina, sem lógica de PPID.
+- **`UserDataCache`**: Novo campo opcional `ppid` para persistir o PPID derivado entre sessões. Retrocompatível — caches legados sem o campo são migrados automaticamente no primeiro boot.
+
+---
+
+## [3.7.9] - 2026-03-12
+
+### Corrigido
+
+- **AAVastPlayer (video_v2 / IMA SDK)**: O último evento de tracking VAST ficava pendente porque `finishWithResult` chamava `cleanup()` imediatamente, destruindo o modal e os elementos DOM antes do delay de 1 segundo previsto para dar tempo aos pixels de tracking do IMA SDK e aos requests HTTP em voo. O fluxo de conclusão normal (REWARDED) — tanto via IMA SDK quanto via fallback `vast-client` — passou a resolver a promise diretamente sem acionar o cleanup, que agora ocorre exclusivamente pelo `setTimeout` de 1 segundo.
+- **AAVastPlayer**: `finishWithResult` não executa mais `cleanup()` internamente. O cleanup passou a ser responsabilidade explícita de cada call site: chamado imediatamente nos fluxos de erro/cancelamento, e diferido via `setTimeout` nos fluxos de conclusão normal, garantindo que os recursos do IMA SDK só sejam destruídos após os pixels de tracking terem tempo de ser enviados.
+
+---
+
 ## [3.7.8] - 2026-03-04
 
 Atualização de versão para sincronização com iOS e Android

package/README.md

@@ -245,6 +245,32 @@ if (media) {
 }
 ```
 
+### Publisher Provided ID (PPID)
+
+Quando `enableGPTPpid: true`, o SDK envia automaticamente um PPID ao Google Ad Manager via GPT para frequency capping, segmentação de audiência e targeting.
+
+O Google Ad Manager exige PPIDs com **32–150 caracteres**. Como userIds internos geralmente não atingem 32 chars, o SDK deriva o PPID via **SHA-256 do userId** (hex de 64 chars), garantindo conformidade. O hash é determinístico: o mesmo userId sempre gera o mesmo PPID, preservando frequency capping entre sessões.
+
+```javascript
+// Uso automático — basta ligar enableGPTPpid na config
+const sdk = await init({
+  baseUrl: 'https://ads.timfun.com.br/adserver/',
+  enableGPTPpid: true,
+  // ...
+});
+
+await sdk.setUserId('user_12345');
+// PPID derivado automaticamente: SHA-256("user_12345") = "d04c992200c84b44..."
+```
+
+Se você já possui um PPID canônico de 32–150 chars, use o escape hatch:
+
+```javascript
+sdk.setPublisherProvidedId('seu-ppid-canonico-com-32-ou-mais-chars');
+```
+
+O PPID também é restaurado automaticamente entre sessões: se o userId já está persistido e `enableGPTPpid` está ligado, o SDK aplica o PPID no GPT durante o `initialize()`, sem necessidade de chamar `setUserId` novamente.
+
 ## 🔧 Configuração
 
 ### Configuração do SDK
@@ -262,7 +288,7 @@ const SDK_CONFIG = {
   primaryColor: '#ff0000',                // Cor primária do projeto (formato hexadecimal)
   luminaToken: 'QQDCYMdFh2AJqwP',         // Token do Lumina SDK (opcional - usa valor padrão se não fornecido)
   proxyExternalScripts: false,           // Carregar scripts externos (GPT, IMA, Lumina) via proxy (opcional)
-  enableGPTPpid: false                   // Enviar userId como PPID para Google Ads via GPT (opcional)
+  enableGPTPpid: true                    // Enviar SHA-256 do userId como PPID para Google Ads via GPT (opcional)
 };
 ```
 
@@ -279,7 +305,7 @@ interface SDKConfig {
   primaryColor?: string;
   luminaToken?: string;
   proxyExternalScripts?: boolean;
-  enableGPTPpid?: boolean;   // Publisher Provided ID para GPT
+  enableGPTPpid?: boolean;   // Envia SHA-256 do userId como PPID para Google Ads via GPT
   cdnBaseUrl?: string;
 }
 ```
@@ -696,8 +722,10 @@ src/
 │   ├── DeviceUtil.ts
 │   ├── ExternalJsLoader.ts     # Carregamento de scripts (GPT, IMA, Lumina)
 │   ├── GlobalLoadingOverlay.ts
+│   ├── GPTPublisherProvidedId.ts # PPID: derivação, persistência e envio ao GPT
 │   ├── logger.ts               # Sistema de logging
 │   ├── PreferencesUtil.ts
+│   ├── sha256.ts               # SHA-256 puro-JS (para derivação de PPID)
 │   ├── version.ts
 │   └── index.ts
 └── index.ts                    # Ponto de entrada principal
@@ -771,7 +799,7 @@ interface SDKConfig {
   primaryColor?: string;
   luminaToken?: string;
   proxyExternalScripts?: boolean;
-  enableGPTPpid?: boolean;   // Publisher Provided ID para GPT
+  enableGPTPpid?: boolean;   // Envia SHA-256 do userId como PPID para Google Ads via GPT
   cdnBaseUrl?: string;
 }
 ```