Pré-requisitos

Conclua estas etapas de pré-requisito antes de instalar o SDK do Singular Flutter para garantir um processo de integração tranquilo.

Instalação

Instalando o pacote SDK

Adicione o Singular SDK do Flutter ao seu projeto usando o gerenciador de dependências pubspec.yaml. O SDK fornece bindings Dart para os SDKs nativos do Singular para iOS e Android.

Adicionar dependência do SDK

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

   dependencies:
     flutter:
       sdk: flutter
     singular_flutter_sdk: ^1.8.0

2. Instalar dependências: Navegue até o 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 do AdServices para rastreamento de atribuição do iOS.

Adicionar a estrutura do AdServices

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

1. Navegue até o 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 Runner.xcworkspace no Xcode (use .xcworkspace se você usar 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 a guia Geral.
   • Desloque-se para a secção Estruturas, bibliotecas e conteúdo incorporado.
   • Clique no botão +.
   • Procure por AdServices.framework e adicione-o.
   • Defina o status da estrutura como Opcional (garante a compatibilidade com versões mais antigas do iOS).

Configuração do Android

Configure seus arquivos de compilação do Android para adicionar as permissões e dependências necessárias para a funcionalidade adequada do SDK.

Adicionar permissões necessárias

Adicione essas permissões ao seu arquivo AndroidManifest.xml sob a tag <manifest> para habilitar 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 rastreio de referenciadores 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 tiver desativado as dependências transitivas para o Singular SDK na sua configuração 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 construir APKs de lançamento, o ProGuard (ou R8) pode remover ou ofuscar classes SDK. Adicione estas regras de manutenção para preservar a funcionalidade Singular.

1. Localizar o arquivo ProGuard: Navegue até android/app/proguard-rules.pro no seu projeto Flutter.
2. Adicionar regras de manutenção: Anexe 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 Singular sempre que seu aplicativo for iniciado. A inicialização do SDK é essencial para todas as funcionalidades de atribuição do Singular e cria uma nova sessão para calcular as métricas de retenção de usuários.

Importar classes do SDK

Importe as classes do SDK do Singular na parte superior do arquivo principal do seu aplicativo (normalmente main.dart).

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

Inicializar o SDK

Crie um objeto SingularConfig com suas credenciais do SDK, configure recursos opcionais e inicialize o SDK usando o método start().

Inicialização básica

1. Obter credenciais: Faça login na sua conta Singulare navegue até Ferramentas do desenvolvedor > Integração do SDK > Chaves do SDKpara encontrar sua chave e segredo do SDK.
2. Criar configuração: Instanciar um objeto SingularConfig com suas credenciais.
3. Adicionar configuração: Opcionalmente, configure o comportamento do SDK usando definidores de propriedade (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 do seu aplicativo, normalmente no 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'
    );

    // 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ários recursos 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(),
    );
  }
}