Suporte a SKAdNetwork

SKAdNetwork é a estrutura de atribuição focada na privacidade da Apple para campanhas de instalação de aplicativos iOS. O Singular SDK do Flutter habilita a SKAdNetwork por padrão no Managed Mode, onde o Singular atualiza automaticamente os valores de conversão com base no modelo de conversão configurado no dashboard.

Entendendo os modos SKAN

Modo gerenciado (padrão)

No Managed Mode, o Singular lida automaticamente com as atualizações do valor de conversão com base no modelo de conversão que você configura no seu painel. Esta é a abordagem recomendada para a maioria das aplicações, uma vez que requer um código mínimo e fornece um rastreamento de conversão ideal.

• Atualizações automáticas: O Singular gerencia todas as atualizações de valores de conversão com base nos eventos do usuário e no seu modelo configurado.
• Configuração do painel: Projete seu modelo de conversão no dashboard do Singular sem alterações de código.
• Otimização: Beneficie-se da experiência da Singular em maximizar as atualizações do valor de conversão dentro das restrições da Apple.
• Gestão de janelas 24 horas: A Singular gere a janela de atualização de 24 horas da SKAdNetwork de forma inteligente para maximizar a recolha de dados.

Modo manual (avançado)

O Modo manual oferece controle total sobre as atualizações de valores de conversão, permitindo implementar uma lógica personalizada para determinar quando e como atualizar os valores de conversão do SKAN. Utilize este modo apenas se tiver requisitos específicos que o Modo Gerido não possa cumprir.

Desativar o suporte de SKAdNetwork

O rastreio de SKAdNetwork está ativado por predefinição. Para o desativar, defina a propriedade de configuração skAdNetworkEnabled como false ao criar o objeto SingularConfig.

import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET');
config.skAdNetworkEnabled = false; // Disable SKAdNetwork

Configurando o modo manual

Para implementar uma lógica de valor de conversão personalizada, active o Modo manual e utilize os métodos SDK fornecidos para atualizar e monitorizar os valores de conversão ao longo do ciclo de vida da aplicação.

Ativar o Modo manual

Defina a propriedade de configuração manualSkanConversionManagement como true ao criar seu objeto SingularConfig para assumir o controle das atualizações de valores de conversão.

import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET');
config.manualSkanConversionManagement = true; // Enable manual mode

Atualizar valor de conversão (SKAN 2.0-3.0)

Utilize o método skanUpdateConversionValue para atualizar manualmente o valor de conversão SKAdNetwork com base na sua lógica personalizada. O valor de conversão tem de ser um número inteiro entre 0 e 63.

Assinatura do método

static void skanUpdateConversionValue(int conversionValue)

Exemplo de utilização

import 'package:singular_flutter_sdk/singular.dart';
import 'dart:io';

// User completed signup - update conversion value to 7
void onUserSignUp() {
  if (Platform.isIOS) {
    // Track the sign-up event
    Singular.event('SignUp');

    // Update SKAN conversion value
    Singular.skanUpdateConversionValue(7);
    print('Conversion value updated to 7');
  }
}

// User completed purchase - update based on purchase amount
void onPurchaseComplete(double purchaseAmount) {
  if (Platform.isIOS) {
    // Track revenue event
    Singular.customRevenue('Purchase', 'USD', purchaseAmount);

    // Calculate conversion value based on purchase tier
    int conversionValue = calculateConversionValue(purchaseAmount);
    Singular.skanUpdateConversionValue(conversionValue);
    print('Conversion value updated to $conversionValue');
  }
}

int calculateConversionValue(double amount) {
  // Your custom logic to determine conversion value
  if (amount >= 100) return 63;  // High value
  if (amount >= 50) return 40;   // Medium value
  if (amount >= 10) return 20;   // Low value
  return 10;                      // Minimal value
}

Atualizar valores de conversão (SKAN 4.0)

Para iOS 16.1+, utilize o método skanUpdateConversionValues para atualizar os valores de conversão SKAdNetwork 4.0 com parâmetros de valor fino, valor grosso e bloqueio. Isto proporciona um controlo mais granular sobre as actualizações dos valores de conversão.

Assinatura do método

static void skanUpdateConversionValues(
  int conversionValue,  // Fine value (0-63)
  int coarse,           // Coarse value (0=low, 1=medium, 2=high)
  bool lock             // Lock status
)

Exemplo de utilização

import 'package:singular_flutter_sdk/singular.dart';
import 'dart:io';

void updateSKAN4ConversionValue(
  int fineValue, 
  String coarseValue,
  bool shouldLock
) {
  if (Platform.isIOS) {
    // Map coarse value string to number
    Map<String, int> coarseMap = {
      'low': 0, 
      'medium': 1, 
      'high': 2
    };

    // Update SKAdNetwork 4.0 conversion values
    Singular.skanUpdateConversionValues(
      fineValue,
      coarseMap[coarseValue] ?? 0,
      shouldLock
    );

    print('SKAN 4.0 updated: fine=$fineValue, coarse=$coarseValue, lock=$shouldLock');
  }
}

// Example: High-value user completes tutorial
void onTutorialComplete() {
  updateSKAN4ConversionValue(15, 'medium', false);
}

// Example: Premium purchase - lock the value
void onPremiumPurchase() {
  updateSKAN4ConversionValue(63, 'high', true);
}

Obter valor de conversão atual

Recupera o valor de conversão atual rastreado pelo SDK Singular. Isso é útil para implementar a lógica condicional com base no estado atual e funciona nos modos Gerenciado e Manual.

Assinatura do método

static Future<int> skanGetConversionValue()

Exemplo de uso

import 'package:singular_flutter_sdk/singular.dart';
import 'dart:io';

Future<void> checkAndUpdateConversionValue() async {
  if (Platform.isIOS) {
    int currentValue = await Singular.skanGetConversionValue();
    print('Current conversion value: $currentValue');

    // Only update if current value is below threshold
    if (currentValue < 30) {
      Singular.skanUpdateConversionValue(30);
      print('Updated conversion value to 30');
    }
  }
}

Monitorar atualizações de valor de conversão

Configure um manipulador para receber notificações em tempo real sempre que o valor de conversão for alterado. Isto permite-lhe reagir às actualizações do valor de conversão e registar análises ou desencadear outros comportamentos da aplicação.

Configuração

Configure o manipulador de atualização do valor de conversão usando a propriedade conversionValueUpdatedCallback ao inicializar o SDK.

import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';

void initializeSingularSDK() {
  SingularConfig config = SingularConfig('API_KEY', 'SECRET');

  // Set up conversion value update handler
  config.conversionValueUpdatedCallback = (int conversionValue) {
    print('Conversion value updated to: $conversionValue');

    // Log the update to your analytics
    logConversionValueUpdate(conversionValue);

    // Trigger app-specific behavior
    if (conversionValue >= 50) {
      unlockPremiumFeature();
    }
  };

  Singular.start(config);
}

void logConversionValueUpdate(int value) {
  // Your analytics logging logic
  print('Analytics: SKAN CV = $value');
}

void unlockPremiumFeature() {
  // Your custom logic
  print('Premium feature unlocked based on high conversion value');
}

Suporte ao App Tracking Transparency (ATT)

O App Tracking Transparency (ATT) é a estrutura de privacidade da Apple que requer o consentimento do utilizador antes de aceder ao IDFA (Identificador para Anunciantes) do dispositivo e partilhar dados do utilizador. A implementação correta da ATT é fundamental para a atribuição do iOS e para maximizar a precisão das suas campanhas de aquisição de utilizadores.

Por que a ATT é importante para a atribuição

A partir do iOS 14.5, os aplicativos devem solicitar permissão do usuário por meio da estrutura ATT antes de acessar o IDFA. Embora a atribuição ainda seja possível sem o IDFA usando impressão digital e métodos probabilísticos, ter o IDFA melhora significativamente a precisão da atribuição e fornece correspondência determinística.

• Atribuição determinística: O IDFA permite uma atribuição precisa, ao nível do dispositivo, que liga as impressões de anúncios diretamente às instalações.
• Otimização da rede de anúncios: As redes de anúncios podem otimizar melhor as campanhas e fornecer relatórios mais precisos com o acesso ao IDFA.
• Informações ao nível do utilizador: O acesso ao IDFA permite uma análise mais granular do comportamento do utilizador e um acompanhamento de coortes.

Requisitos de implementação

Para iOS 14.5+ (incluindo iOS 18), use a estrutura ATTrackingManager para solicitar o consentimento do usuário antes de acessar o IDFA para rastreamento. O SDK Singular é compatível com ATT, permitindo a inicialização antes do consentimento e atrasando eventos até que o consentimento seja concedido ou ocorra um tempo limite.

Etapa 1: Adicionar configuração de estrutura ATT

Configure seu aplicativo iOS para oferecer suporte à estrutura ATT atualizando seu arquivo Info.plist com uma descrição de uso voltada para o usuário.

1. Abra o Info.plist: Navegue até ao ficheiro Info.plist do seu projeto Flutter para iOS (localizado em ios/Runner/Info.plist).
2. Adicionar descrição de uso: Adicione a chave NSUserTrackingUsageDescription com uma explicação clara da razão pela qual a sua aplicação precisa de permissão de rastreio.

<key>NSUserTrackingUsageDescription</key>
<string>This app uses tracking to provide personalized ads and improve your experience.</string>

Etapa 2: Instalar o pacote de suporte ATT

Instale um pacote de suporte Flutter ATT para ativar a funcionalidade ATT na sua aplicação. Recomendamos o plugin app_tracking_transparency.

Adicionar dependência

dependencies:
  flutter:
    sdk: flutter
  singular_flutter_sdk: ^1.8.0
  app_tracking_transparency: ^2.0.4

Depois de adicionar a dependência, execute flutter pub get para instalar o pacote.

flutter pub get

Etapa 3: configurar o tempo limite de espera do SDK

Configure o SDK Singular para aguardar a resposta ATT do usuário antes de inicializar, definindo a propriedade waitForTrackingAuthorizationWithTimeoutInterval. Esse atraso garante que o IDFA seja capturado se o usuário conceder permissão.

import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET');
config.waitForTrackingAuthorizationWithTimeoutInterval = 300; // Wait up to 5 minutes

Passo 4: Pedir o consentimento da ATT

Implemente o fluxo de pedidos ATT na sua aplicação, solicitando aos utilizadores a permissão de rastreio num momento adequado da sua experiência de utilizador.

import 'package:flutter/material.dart';
import 'dart:io';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:app_tracking_transparency/app_tracking_transparency.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    initializeApp();
  }

  Future<void> initializeApp() async {
    if (Platform.isIOS) {
      // Request ATT authorization
      final trackingStatus = await AppTrackingTransparency.requestTrackingAuthorization();

      // Log the user's response
      print('ATT Status: $trackingStatus');
      // Possible values: TrackingStatus.authorized, .denied, .restricted, .notDetermined
    }

    // Initialize Singular SDK (configured with wait timeout)
    SingularConfig config = SingularConfig('API_KEY', 'SECRET');
    config.waitForTrackingAuthorizationWithTimeoutInterval = 300;
    config.enableLogging = true;

    Singular.start(config);
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: MyHomePage(),
    );
  }
}

Compreender o fluxo ATT

Quando você define um atraso de inicialização usando waitForTrackingAuthorizationWithTimeoutInterval, o fluxo do aplicativo funciona da seguinte maneira:

1. Quando o aplicativo é aberto, o Singular SDK começa a gravar uma sessão e eventos do usuário, mas ainda não os envia para o servidor Singular.
2. Quando o consentimento do App Tracking Transparency é concedido/negado ou o tempo definido passa, o SDK envia a sessão e quaisquer eventos em fila para o servidor Singular (com ou sem o IDFA).
3. Em seguida, o Singular inicia o processo de atribuição, aproveitando o IDFA se ele estiver disponível.

Cenários ATT

A tabela a seguir resume os cenários possíveis usando essa integração:

Melhores práticas da ATT

• Mensagens de pré-prompt: Mostre aos utilizadores um ecrã pré-ATT que explique por que razão necessita de permissão de rastreio e como isso os beneficia (melhores anúncios, melhor experiência). Isto pode aumentar significativamente as taxas de aceitação.
• O momento é importante: Mostre o prompt ATT em um momento natural no fluxo do aplicativo, não imediatamente no primeiro lançamento. Deixe que os utilizadores experimentem primeiro a sua aplicação para criar confiança.
• Configuração do tempo limite: Defina waitForTrackingAuthorizationWithTimeoutInterval para 30-300 segundos. Após o tempo limite, o Singular prossegue com a atribuição SKAN 4.0 (sem IDFA).
• Teste minuciosamente: Teste cenários autorizados e negados para garantir que seu aplicativo funcione corretamente, independentemente da escolha do usuário.
• Respeitar a escolha do utilizador: Nunca solicite repetidamente aos utilizadores que tenham negado o rastreio ou mostre mensagens agressivas que os pressionem a aceitar.
• Tratamento de erros: Verifique o estado do rastreio para restricted (por exemplo, controlos parentais) ou notDetermined e registe para análise.
• Integração do SKAN 4.0: Certifique-se de que as actualizações do valor de conversão estão alinhadas com o consentimento da ATT para otimizar os postbacks do SKAN (por exemplo, utilize o dashboard da Singular para mapear eventos para os valores 0-63).

Recursos adicionais

• Documentação da estrutura de transparência de rastreamento de aplicativos da Apple
• Práticas de ativação e desativação do SDK Singular
• Diretrizes de privacidade do usuário e uso de dados da Apple
• Guia SKAdNetwork da Singular
• Plug-in de transparência de rastreamento de aplicativos do Flutter