Akross Artemis Ads SDK v4.1.1 - Flutter

SDK Flutter para integração com o sistema de anúncios Akross Artemis. Este pacote fornece uma interface simples e eficiente para gerenciar anúncios em aplicações Flutter.

🚀 Características

✅ Inicialização simples do SDK com configuração automática
✅ Gerenciamento de estado da inicialização e usuário
✅ Configuração flexível de usuário e headers customizados
✅ Sistema de logging integrado com níveis de debug
✅ Persistência de configurações automática
✅ Compatibilidade total com Android, iOS e Web
✅ Display Ads com waterfall programático
✅ Interstitial Ads com fallback de imagem
✅ Tracking de eventos com retry automático
✅ Classes utilitárias para dimensões, URLs e eventos

Instalação

Adicione ao seu pubspec.yaml:

dependencies:
  akross_artemis_sdk: ^4.1.1

📱 Uso Básico

1. Inicialização

import 'package:akross_artemis_sdk/akross_artemis_sdk.dart';

final aaManager = AAManager();

// Configurar o SDK
final config = SDKConfig(
  baseUrl: 'https://ads.timfun.com.br/adserver/',
  debugMode: true,
  timeout: 10000,
  testMode: true,
  // appId e appVersion são opcionais - serão detectados automaticamente
  // appId: 'com.example.myapp', // Opcional
  // appVersion: '1.0.0', // Opcional
);

await aaManager.initialize(config);

Configuração de SDKs de Anúncios

O SDK suporta inicialização automática do Google Ads:

⚠️ Importante: O Google Ad Manager App ID deve estar no AndroidManifest.xml:

<!-- android/app/src/main/AndroidManifest.xml -->
<meta-data
    android:name="com.google.android.gms.ads.APPLICATION_ID"
    android:value="ca-app-pub-XXXXXXXXXX~XXXXXXXXXX"/>

// Configuração com Google Ads (App ID no manifest)
final config = SDKConfig(
  baseUrl: 'https://ads.timfun.com.br/adserver/',
  debugMode: true,
  testMode: true,
);

Detecção Automática de App ID e Versão

O SDK pode detectar automaticamente o appId e appVersion do app hospedeiro:

// Detecção automática (recomendado)
final config = SDKConfig(
  baseUrl: 'https://ads.timfun.com.br/adserver/',
  debugMode: true,
  // appId e appVersion serão obtidos automaticamente do package_info
);

// Ou especificar manualmente
final config = SDKConfig(
  baseUrl: 'https://ads.timfun.com.br/adserver/',
  debugMode: true,
  appId: 'com.example.myapp',
  appVersion: '1.0.0',
);

2. Gerenciamento de Usuário

// Definir ID do usuário
await aaManager.setUserId('user123', advertisingId: 'ad456');

// Obter ID do usuário
final userId = await aaManager.getUserId();

// Obter dados completos do usuário
final userData = await aaManager.getUserData();

3. Headers Customizados

// Definir headers customizados
await aaManager.setCustomHeaders({
  'Authorization': 'Bearer token123',
  'X-Custom-Header': 'value',
});

// Obter headers customizados
final headers = await aaManager.getCustomHeaders();

// Remover headers customizados
await aaManager.removeCustomHeaders();

4. Debug e Informações

// Verificar se o SDK está inicializado
final isInitialized = aaManager.isInitialized;

// Obter informações de debug
final debugInfo = await aaManager.getDebugInfo();
print(debugInfo);

5. Limpeza

// Limpar todas as configurações
await aaManager.clearAll();

🎯 Tipos de Anúncios

// Widget para exibir display ads com waterfall
AkrossDisplayAd(
  zoneId: 'your-zone-id',
  adSize: AAMediaSize.SMALL, // SMALL, MEDIUM, ANCHOR, INLINE
  onAdShow: () => print('Anúncio exibido'),
  onAdError: (error) => print('Erro: $error'),
  onAdClicked: () => print('Anúncio clicado'),
)

Tamanhos disponíveis:

AAMediaSize.SMALL: Banner pequeno (90-120px altura)
AAMediaSize.MEDIUM: Banner médio (320-355px altura)
AAMediaSize.ANCHOR: Banner adaptativo ancorado (50-100px altura)
AAMediaSize.INLINE: Banner adaptativo inline (50-250px altura)

Interstitial Ads

// Exibir interstitial com waterfall
await AAInterstitialAdHelper.handle(
  'your-zone-id',
  context: context,
  onAdShow: () => print('Interstitial exibido'),
  onAdDismiss: () => print('Interstitial fechado'),
  onAdError: (error) => print('Erro: $error'),
  onAdClicked: () => print('Interstitial clicado'),
);

Outra opção é fazer o pré-carregamento separado da exibição:

// Pré-carregar interstitial
final loader = await AAInterstitialAdHelper.fetch(
  'your-zone-id'
  onAdShow: () => print('Interstitial exibido'),
  onAdDismiss: () => print('Interstitial fechado'),
  onAdError: (error) => print('Erro: $error'),
  onAdClicked: () => print('Interstitial clicado'),
);
// Aguardar carregamento
await loader.wait;
// Exibir interstitial
await loader.show(context);

🔧 Classes Utilitárias

AdDimensionsHelper

// Obter constraints para anúncios
final constraints = AdDimensionsHelper.getConstraints(
  AAMediaSize.SMALL, 
  context
);

UrlHelper

// Abrir URLs
UrlHelper.openUrl('https://example.com');

// Validar URLs
bool isValid = UrlHelper.isValidUrl('https://example.com');

EventTrackingHelper

// Enviar eventos de tracking
EventTrackingHelper.sendEvent(
  EventConstants.impression,
  logger,
  currentMedia: currentMedia,
);

Fluxo de Eventos Esperados

Cenário 1: Sucesso com Anúncio Programático

waterfall-start → impression → click

Cenário 2: No Fill + Fallback

waterfall-start → prog-ad-no-fill → fallback-req → impression_nffb → click_nffb

Cenário 3: Erro de Conexão + Fallback

waterfall-start → prog-conn-error → fallback-req → impression_nffb → click_nffb

Cenário 4: Erro de Anúncio + Fallback

waterfall-start → prog-ad-error → fallback-req → impression_nffb → click_nffb

Cenário 5: Falha Total (Sem Fallback)

waterfall-start → prog-ad-no-fill → prog-conn-error → (sem eventos)

Interstitial Ads

Cenário 1: Sucesso com Anúncio Programático

waterfall-start → impression → click → dismiss

Cenário 2: No Fill + Fallback

waterfall-start → prog-ad-no-fill → fallback-req → impression_nffb → click_nffb → dismiss

Cenário 3: Erro de Conexão + Fallback

waterfall-start → prog-conn-error → fallback-req → impression_nffb → click_nffb → dismiss

Cenário 4: Erro de Anúncio + Fallback

waterfall-start → prog-ad-error → fallback-req → impression_nffb → click_nffb → dismiss

Cenário 5: Falha Total (Sem Fallback)

waterfall-start → prog-ad-no-fill → prog-conn-error → (sem eventos)

Eventos de Tracking

Eventos de Waterfall:

waterfall-start: Início do processo de waterfall
prog-ad-no-fill: Anúncio programático sem fill
prog-ad-error: Erro no anúncio programático
prog-conn-error: Erro de conexão
fallback-req: Requisição de fallback

Eventos de Impressão:

impression: Anúncio programático exibido
impression_nffb: Anúncio fallback exibido (no fill + fallback)

Eventos de Interação:

click: Clique em anúncio programático
click_nffb: Clique em anúncio fallback
dismiss: Fechamento de interstitial

Fluxo de Dados do Dispositivo

O SDK coleta automaticamente dados do dispositivo para melhorar a segmentação:

// Dados básicos (sempre coletados)
{
  "deviceId": "a1b2c3d4e5f6g7h8",        // Android ID ou iOS identifierForVendor
  "sdkVersion": "4.1.1",                  // Versão do SDK (centralizada em AAManager.getSdkVersion())
  "os": "ANDROID",                        // Sistema operacional
  "brand": "Samsung",                     // Marca do dispositivo
  "model": "SM-G973F",                    // Modelo do dispositivo
  "manufacturer": "Samsung",               // Fabricante
  "hardware": "Android 13",              // Hardware
  "product": "android",                   // Produto do sistema
  "osVersion": "13",                      // Versão do OS
  "eventDate": "1760709937741"            // Timestamp
}

// Dados opcionais (apenas se permissões concedidas)
{
  "battery": "85",                        // Nível da bateria (0-100%)
  "carrier": "Vivo",                      // Nome da operadora
  "lat": "-23.5505",                      // Latitude
  "long": "-46.6333"                      // Longitude
}

Fluxo de Coleta de Dados:

Inicialização: SDK coleta dados básicos do dispositivo
Verificação de Permissões: Verifica se tem permissões para dados sensíveis
Coleta Condicional: Coleta dados extras apenas se tiver permissões
Envio: Inclui dados no contexto das requisições de anúncios

Fluxo de Waterfall

O SDK implementa um sistema de waterfall para otimizar a entrega de anúncios:

// 1. Requisição inicial
POST /campaign/v3/{zoneId}?size={size}
{
  "userId": "user123",
  "context": { /* dados do dispositivo */ }
}

// 2. Resposta do servidor
{
  "waterfall": [
    {
      "type": "PROGRAMMATIC",
      "network": "GOOGLE_ADS",
      "adUnitId": "ca-app-pub-xxx/xxx",
      "priority": 1
    },
    {
      "type": "FALLBACK",
      "imageUrl": "https://example.com/fallback.jpg",
      "clickUrl": "https://example.com",
      "priority": 3
    }
  ]
}

// 3. Execução do waterfall
// ✅ Tenta Google Ads (prioridade 1)
// ❌ Falha → Exibe fallback (prioridade 2)

Exemplo Completo

Veja o arquivo example/lib/main.dart para um exemplo completo de uso.

📁 Estrutura do Projeto

lib/
├── src/
│   ├── core/                        # Núcleo do SDK
│   │   ├── aa_manager.dart          # Classe principal do SDK
│   │   ├── config/
│   │   │   └── sdk_config.dart      # Configuração do SDK
│   │   ├── model/                   # Modelos de dados
│   │   └── network/                  # Camada de rede
│   ├── modules/                     # Módulos de anúncios
│   │   ├── display/                 # Display ads
│   │   │   ├── akross_display_ad.dart
│   │   │   └── widgets/
│   │   └── interstitial/             # Interstitial ads
│   │       ├── interstitial_helper.dart
│   │       └── widgets/
│   ├── ads/                         # Gerenciadores de anúncios
│   │   └── google_ads_manager.dart
│   ├── ads_core/                    # Core de anúncios
│   │   └── ads_manager.dart
│   └── utils/                        # Utilitários
│       ├── logger.dart              # Sistema de logging
│       ├── preferences_util.dart    # Persistência
│       ├── ad_dimensions_helper.dart # Dimensões
│       ├── url_helper.dart          # URLs
│       └── event_tracking_helper.dart # Eventos
└── akross_artemis_sdk.dart         # Arquivo principal de exportação

Compatibilidade

Flutter: >=1.17.0
Dart: ^3.6.0
Android: API 21+
iOS: 11.0+
Web: Todas as versões modernas

📦 Dependências

Principais

shared_preferences: Para persistência de dados
http: Para requisições HTTP
json_annotation: Para serialização JSON
package_info_plus: Para informações do app

Anúncios

google_mobile_ads: Google Mobile Ads

Utilitários

url_launcher: Para abrir URLs
device_info_plus: Informações do dispositivo

Contribuição

Este SDK é compatível com as versões JavaScript, Android e iOS do Akross Artemis SDK, mantendo a mesma interface e funcionalidades.

Akross Artemis Ads SDK v4.1.1 - Flutter

🚀 Características

Instalação

📱 Uso Básico

1. Inicialização

Configuração de SDKs de Anúncios

Detecção Automática de App ID e Versão

2. Gerenciamento de Usuário

3. Headers Customizados

4. Debug e Informações

5. Limpeza

🎯 Tipos de Anúncios

Display Ads (Banner)

Interstitial Ads

🔧 Classes Utilitárias

AdDimensionsHelper

UrlHelper

EventTrackingHelper

Fluxo de Eventos Esperados

Display Ads (Banner)

Cenário 1: Sucesso com Anúncio Programático

Cenário 2: No Fill + Fallback

Cenário 3: Erro de Conexão + Fallback

Cenário 4: Erro de Anúncio + Fallback

Cenário 5: Falha Total (Sem Fallback)

Interstitial Ads

Cenário 1: Sucesso com Anúncio Programático

Cenário 2: No Fill + Fallback

Cenário 3: Erro de Conexão + Fallback

Cenário 4: Erro de Anúncio + Fallback

Cenário 5: Falha Total (Sem Fallback)

Eventos de Tracking

Eventos de Waterfall:

Eventos de Impressão:

Eventos de Interação:

Fluxo de Dados do Dispositivo

Fluxo de Waterfall

Exemplo Completo

📁 Estrutura do Projeto

Compatibilidade

📦 Dependências

Principais

Anúncios

Utilitários

Contribuição

Libraries

akross_artemis_sdk package