Antes de começar: Pré-requisitos do SDK

O SDK do Singular está disponível como um plug-in para o Flutter. As instruções abaixo mostram como integrar o Singular em seu aplicativo Flutter.

• Este artigo assume que você tem um aplicativo Flutter funcional.
• Para inicializar o SDK, você precisa da sua Chave SDK Singular e do Segredo SDK. Você pode obtê-los na plataforma Singular em"Developer Tools > SDK Integration > SDK Keys".

Integrar o SDK

Para adicionar o plugin Singular ao seu aplicativo Flutter, adicione as seguintes linhas ao seu arquivo pubspec.yaml:

dependencies:
  singular_flutter_sdk: ^1.6.1

Em seguida, navegue até o seu projeto no terminal e execute o seguinte:

flutter packages get

Etapas adicionais para Android

Adicionando dependências

Para aplicativos Android, você precisa adicionar a biblioteca Singular à lista de dependências em app/build.gradle, como segue:

dependencies {  
  implementation fileTree(dir: 'libs', include: ['*.jar'])
  implementation 'com.android.support:appcompat-v7:28.0.0'
  //...
}

O SDK do Singular requer a API do Google Mobile Ads, parte das APIs do Google Play Services 17.0.0+. Se já integrou o Google Play Services na sua aplicação, o requisito está cumprido. Se não o tiver feito, pode integrar o Google Mobile Ads individualmente, incluindo a seguinte dependência no build.gradle da sua aplicação:

implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'

Se tiver desativado as dependências transitivas para o SDK Singular, adicione o seguinte ao build.gradle da sua aplicação.

implementation 'com.android.installreferrer:installreferrer:2.2'
implementation 'com.google.android.gms:play-services-appset:16.0.2'

Além disso, adicione o seguinte para suportar o referenciador de instalação da Samsung Galaxy Store se a sua aplicação for distribuída através da Samsung Galaxy Store:

implementation 'store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:4.0.0'

Adicionar permissões

Adicione essas permissões sob a tag <manifest> no seu arquivo AndroidManifest.xml:

<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" />

Adicionalmente, adicione o seguinte para suportar o referenciador de instalação da Samsung Galaxy Store se a sua aplicação for distribuída através da Samsung Galaxy Store e tiver como alvo o Android 11 ou superior:

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

Se a compilação da sua aplicação tiver como alvo o Android 12/API nível 31 ou superior, adicione permissões para aceder ao ID de publicidade do Google:

<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

Etapas adicionais para iOS

Para usar o plug-in Singular, é necessário adicionar a estrutura AdServices.

Inicializando o SDK do Singular

O código de inicialização do Singular SDK deve ser chamado sempre que seu aplicativo for aberto. Ele é um pré-requisito para todas as funcionalidades de atribuição do Singular e também envia uma nova sessão de usuário para o Singular (as sessões são usadas para calcular a retenção de usuários).

O código de inicialização vai no widget principal do aplicativo (ou seja, main.dart) - o primeiro que é carregado quando o aplicativo é aberto. Este widget tem de ter estado, e o código tem de ser adicionado no método initState() do widget.

1. Primeiro, é preciso criar um objeto SingularConfig. O objeto contém a chave e o segredo do Singular SDK.
2. Opcionalmente, pode adicionar definições para ativar várias funcionalidades do SDK. Veja a lista completa de opções.
3. META Instalar suporte à atribuição de referenciador

   Configuração necessária do SDK para ativar a atribuição do "Meta Install Referrer":

   1. Forneça seu ID do aplicativo do Facebook no objeto de configuração Singular.
      

      // To enable META Install Referrer
      
      
                config.facebookAppId = "INSERT YOUR FACEBOOK APP ID HERE";

   Onde posso encontrar a ID de aplicativo do Facebook de um aplicativo?

Exemplo:

import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
//...
class MyHomePage extends StatefulWidget { 
  //...
  }
  
  class _MyHomePageState extends State<MyHomePage> {
    //...
    @override 
    void initState() {
      super.initState();
      //...
      SingularConfig config = new SingularConfig('SDK KEY', 'SDK SECRET');
      // Set hashed User ID if available


      config.customUserId = "b642b4217b34b1e8d3bd915fc65c4452";
      
      // For iOS (Remove this if you are not displaying an ATT prompt)!


      config.waitForTrackingAuthorizationWithTimeoutInterval = 300;
      
      // To enable SkAdNetwork Support


      config.skAdNetworkEnabled = true;
      
      // To enable META Install Referrer


      config.facebookAppId = "INSERT YOUR FACEBOOK APP ID HERE";
      
      // (optional) Using Singular Global Properties feature to capture 


      // third party identifiers. The respective SDK(s) must be initialized


      // before the Singular SDK. Example of passing the CleverTapID.


      // var cleverTapId = CleverTapPlugin.getCleverTapID();


      // config.withGlobalProperty("CLEVERTAPID", cleverTapId, true);


              
      Singular.start(config);
  }

Como lidar com o consentimento ATT (definir um atraso de inicialização)

Exibindo um prompt ATT (Transparência de rastreamento de aplicativo)

A partir do iOS 14.5, as aplicações são obrigadas a pedir o consentimento do utilizador (utilizando a estrutura App Tracking Transparency) antes de poderem aceder e partilhar alguns dados do utilizador que são úteis para fins de rastreio, incluindo o IDFA do dispositivo.

A Singular beneficia muito de ter o IDFA para identificar dispositivos e efetuar a atribuição de instalações (embora existam formas de efetuar a atribuição sem o IDFA). Recomendamos vivamente que peça o consentimento do utilizador para obter o IDFA.

Atraso na inicialização para aguardar a resposta da ATT

Por padrão, o Singular SDK envia uma sessão de usuário quando é inicializado. Quando uma sessão é enviada de um novo dispositivo, ela aciona imediatamente o processo de atribuição do Singular - que é realizado com base apenas nos dados disponíveis para o Singular naquele momento. Portanto, é essencial solicitar o consentimento e recuperar o IDFA antes que o SDK do Singular envie a primeira sessão.

Para atrasar o disparo de uma sessão de usuário, inicialize o Singular SDK com a opção waitForTrackingAuthorizationWithTimeoutInterval no objeto Config. Essa opção já está incluída no exemplo de código acima.

Adicionando suporte a SKAdNetwork

Para habilitar o rastreamento de SKAdNetwork para seu aplicativo, habilite a opção de configuração skAdNetworkEnabled antes de inicializar o Singular.

Modo gerenciado (recomendado)

No modo gerenciado, Singular gerencia automaticamente o valor de conversão de SKAdNetwork para você, com base em um modelo de conversão de sua escolha que pode ser configurado na plataforma Singular.

Para saber mais, consulte Entendendo o gerenciamento do valor de conversão da Singular e as Perguntas frequentes sobre a configuração do modelo SKAdNetwork. Para obter um guia passo a passo sobre como usar a SKAdNetwork com a Singular, consulte Como começar a usar a SKAdNetwork.

Nota: o modo SKAN Managed já está ativado no trecho de código de inicialização acima. Certifique-se de que tem estes itens de configuração definidos.

Para ativar a SKAdNetwork no modo gerenciado, use o código a seguir:

SingularConfig config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
config.skAdNetworkEnabled = true;
config.waitForTrackingAuthorizationWithTimeoutInterval = 300;
Singular.init(config);

Modo manual

Se já tiver a sua própria estratégia e ferramentas para gerir o valor de conversão da SKAdNetwork, pode ativar a SKAdNetwork no modo manual.

SingularConfig config = new SingularConfig('SDK KEY', 'SDK SECRET');
config.skAdNetworkEnabled = true;
config.manualSkanConversionManagement = true;
config.waitForTrackingAuthorizationWithTimeoutInterval = 300;
Singular.init(config);

Depois, para atualizar o valor de conversão, utilize o seguinte código:

ingular.skanUpdateConversionValue(conversionValue)

Para saber quando o valor de conversão é alterado, utilize a seguinte função de retorno de chamada:

config.conversionValueUpdatedCallback = (int conversionValue) {
  print('Received conversionValueUpdatedCallback: ' + conversionValue.toString());
};

Para recuperar o valor de conversão atual, utilize o seguinte código:

Singular.skanGetConversionValue().then((conversionValue) {
  print('conversion value: ' + conversionValue.toString());
});