Instalação

Instalação do pacote SDK

Adicione o SDK Singular Flutter ao seu projeto utilizando o gestor de dependências pubspec.yaml. O SDK fornece ligações Dart aos SDKs nativos da Singular para iOS e Android.

Adicionar dependência do SDK

1. Atualize o pubspec.yaml: Adicione a dependência do SDK Singular Flutter ao ficheiro ` pubspec.yaml ` do seu projeto:
   pubspec.yaml

   dependencies:
     flutter:
       sdk: flutter
     singular_flutter_sdk: ^1.8.0

2. Instalar dependências: Navegue até ao diretório do seu projeto no terminal e execute:
   bash

   flutter packages get

Configuração da plataforma

Configuração do iOS

Conclua a configuração específica do iOS para ativar o suporte da estrutura AdServices para o rastreamento de atribuição no iOS.

Adicionar a estrutura AdServices

A estrutura AdServices é necessária para a atribuição do Apple Search Ads e a integração com o SKAdNetwork no iOS 14.3+.

1. Navegue até ao projeto iOS: Abra o diretório iOS do seu projeto Flutter e localize o espaço de trabalho do Xcode.
   • Navegue até à pasta ios do seu projeto Flutter.
   • Abra o ` Runner.xcworkspace ` no Xcode (use .xcworkspace se utilizar o CocoaPods; caso contrário, use .xcodeproj).
2. Adicione a estrutura AdServices: Configure a estrutura nas definições do seu projeto Xcode.
   • No Xcode, selecione o destino do seu projeto (por exemplo, «Runner»).
   • Vá para o separador Geral.
   • Percorra até à secção Frameworks, Libraries, and EmbeddedContent .
   • Clique no botão +.
   • Procure por « AdServices.framework » e adicione-o.
   • Defina o estado da estrutura como Opcional (garante a compatibilidade com versões mais antigas do iOS).

Configuração do Android

Configure os seus ficheiros de compilação do Android para adicionar as permissões e dependências necessárias para o funcionamento adequado do SDK.

Adicionar permissões necessárias

Adicione estas permissões ao seu ficheiro AndroidManifest.xml sob a tag <manifest> para ativar a funcionalidade principal do SDK.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="BIND_GET_INSTALL_REFERRER_SERVICE" />
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

Suporte da Samsung Galaxy Store

Para ativar o rastreamento de referência de instalação da Samsung Galaxy Store, adicione o seguinte ao seu AndroidManifest.xml:

<queries>
   <package android:name="com.sec.android.app.samsungapps" />
</queries>

Dependências transitivas

Se desativou as dependências transitivas para o Singular SDK na sua configuração do Gradle, adicione manualmente estas dependências necessárias:

dependencies {
    // Required for install referrer tracking
    implementation 'com.android.installreferrer:installreferrer:2.2'

    // Required for App Set ID
    implementation 'com.google.android.gms:play-services-appset:16.0.0'
}

Configuração do ProGuard

Ao compilar APKs de lançamento, o ProGuard (ou R8) pode remover ou ofuscar classes do SDK . Adicione estas regras de retenção para preservar a funcionalidade do Singular.

1. Localize o ficheiro ProGuard: Navegue até android/app/proguard-rules.pro no seu projeto Flutter.
2. Adicione regras de preservação: acrescente as seguintes regras para preservar as classes do SDK:
   android/app/proguard-rules.pro

   # Preserve Singular SDK classes
   -keep class com.singular.sdk.** { *; }
   
   # Preserve Android Install Referrer library
   -keep public class com.android.installreferrer.** { *; }
   
   # Uncomment if using Singular revenue tracking with Google Play Billing Library
   #-keep public class com.android.billingclient.** { *; }

Integração do SDK

Inicialize o SDK da Singular sempre que a sua aplicação for iniciada. A inicialização do SDK é essencial para todas as funcionalidades de atribuição da Singular e cria uma nova sessão para calcular métricas de retenção de utilizadores.

Importar classes do SDK

Importe as classes do SDK da Singular no início do seu ficheiro principal da aplicação (normalmente main.dart).

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

Sobre o SDID

O Singular Device ID (SDID) é um identificador em nível de dispositivo que a Singular gera e gerencia. Em uma integração híbrida, em que este SDK é executado no seu app e o seu servidor também envia eventos pela API Server-to-Server (S2S), enviar o mesmo SDID nesses eventos do lado do servidor os vincula ao mesmo dispositivo que o SDK está rastreando. Isso permite que a Singular atribua a atividade do SDK e do S2S a um único dispositivo sem depender de identificadores de publicidade específicos da plataforma.

Inicialize o SDK

Crie um objeto ` SingularConfig ` com as suas credenciais do SDK, configure funcionalidades opcionais e inicialize o SDK utilizando o método ` start() `.

Inicialização básica

1. Obter credenciais: Inicie sessão na sua conta Singular e aceda a Ferramentas do Desenvolvedor > Integração do SDK > Chaves do SDK para encontrar a sua Chave e Segredo do SDK.
2. Criar configuração: Instancie um objeto SingularConfig com as suas credenciais.
3. Adicione a configuração: Opcionalmente, configure o comportamento do SDK usando definidores de propriedades (consulte Referência de Configuração).
4. Inicializar o SDK: Chame Singular.start() para iniciar o SDK.

Exemplo de inicialização

Inicialize o SDK no ponto de entrada da sua aplicação, normalmente dentro do método initState() do seu StatefulWidget principal.

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

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

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

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

    // Create configuration with credentials
    SingularConfig config = SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    );

    // Log the SDID once the SDK receives it (SDID is enabled by default for new accounts)
    config.sdidReceivedCallback = (String sdid) {
      print('Singular SDID received: $sdid');
    };

    // Enable debug logging
    config.enableLogging = true;
    config.logLevel = 4;

    // Set session timeout (in seconds)
    config.sessionTimeout = 60.0;

    // Initialize SDK
    Singular.start(config);
  }

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

Exemplo de configuração avançada

Configure várias funcionalidades do SDK durante a inicialização, definindo propriedades adicionais no objeto SingularConfig antes de chamar start() .

import 'package:flutter/material.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:singular_flutter_sdk/singular_link_params.dart';
import 'package:singular_flutter_sdk/singular_global_property.dart';

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

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

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

  void initializeSingularSDK() {
    // Create configuration with credentials
    SingularConfig config = SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    );

    // User identification
    config.customUserId = 'user_123456';

    // Privacy settings
    config.limitDataSharing = false;
    
    // Deep linking handler
    config.singularLinksHandler = (SingularLinkParams params) {
      print('Deep link received: ${params.deeplink}');
      print('Passthrough params: ${params.passthrough}');
      print('Is deferred: ${params.isDeferred}');
      // Handle navigation based on deep link
    };

    // Short link timeout
    config.shortLinkResolveTimeOut = 10.0;

    // Facebook integration
    config.facebookAppId = 'YOUR_FACEBOOK_APP_ID';

    // SKAdNetwork settings (iOS)
    config.skAdNetworkEnabled = true;
    config.manualSkanConversionManagement = false;
    config.waitForTrackingAuthorizationWithTimeoutInterval = 30;

    // Conversion value callbacks (iOS)
    config.conversionValueUpdatedCallback = (int conversionValue) {
      print('Conversion value updated: $conversionValue');
    };

    config.conversionValuesUpdatedCallback = (int cv, int coarse, bool lock) {
      print('Fine: $cv, Coarse: $coarse, Locked: $lock');
    };

    // Global properties
    config.globalProperties = [
      SingularGlobalProperty('app_version', '2.5.0', true),
      SingularGlobalProperty('user_tier', 'premium', false)
    ];

    // Debugging
    config.enableLogging = true;
    config.logLevel = 4;

    // Session timeout
    config.sessionTimeout = 60.0;

    // Initialize SDK
    Singular.start(config);
  }

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

Configuração avançada

Necessário para a medição de conversão integrada do Google Ads no iOS

Se a sua aplicação executa campanhas do Google Ads direcionadas a utilizadores do iOS 14.5+, são necessárias etapas adicionais de configuração do SDK para suportar a Medição de Conversão Integrada do iOS (ICM). Isto inclui:

• Integrar o SDK de medição no dispositivo (ODM) do Google
• Atualização para o SDK do Singular para iOS v12.8.1+ (ou v5.5.0+ para Unity, v1.8.0+ para Flutter/Cordova, v3.9.0+ para React Native)
• Adicionar o sinalizador do ligador « -ObjC » e ativar « enableOdmWithTimeoutInterval » em SingularConfig

Nota: A ativação de enableOdmWithTimeoutInterval atrasa a inicialização do SDK e pode adiar os callbacks de deep link. Conclua esta configuração durante a implementação inicial do SDK para evitar trabalho adicional.

Consulte os requisitos técnicos completos do iOS ICM