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.

Pré-requisitos

• 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".

Integrando o plug-in Singular

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

dependencies:
  singular_flutter_sdk: ^1.5.1

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

flutter packages get

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

Além disso, adicione o seguinte para suportar o referenciador de instalação da Samsung Galaxy Store se o seu aplicativo for distribuído 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 pedir consentimento e recuperar o IDFA antes que o Singular SDK 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.

Envio da ID de usuário para a Singular (opcional)

Você pode enviar sua ID de usuário interna para a Singular usando um método do SDK da Singular.

• A ID de usuário pode ser qualquer identificador e não deve expor PII (Informações de identificação pessoal). Por exemplo, não deve utilizar o endereço de correio eletrónico, o nome de utilizador ou o número de telefone de um utilizador. A Singular recomenda o uso de um valor com hash exclusivo apenas para seus dados primários.
• O valor da ID de usuário passado para a Singular também deve ser a mesma ID de usuário interna que você captura em todas as plataformas (Web/Mobile/PC/Console/Offline).
• A Singular incluirá o ID de utilizador nas exportações ao nível do utilizador, ETL e postbacks do BI interno (se configurado). O ID do usuário é um dado primário e a Singular não o compartilha com outras partes.
• O valor da ID de usuário, quando definido com o método Singular SDK, persistirá até que seja desmarcado usando o método unsetCustomUserId ou até que o aplicativo seja desinstalado. Fechar ou reiniciar a aplicação não anula a definição do ID de utilizador.

Para definir o ID de utilizador, utilize o método setCustomUserId. Para a anular (por exemplo, se o Utilizador "sair" da conta), ligue para unsetCustomUserId.

Se você já sabe a ID de usuário quando o aplicativo é aberto, chame setCustomUserId antes de inicializar o SDK do Singular. Dessa forma, o Singular pode ter a ID de usuário desde a primeira sessão. No entanto, a ID de usuário normalmente não está disponível até que o usuário se registre ou faça um login. Nesse caso, chame setCustomUserId depois que o fluxo de registro for concluído.

Singular.setCustomUserId("custom_user_id");

Singular.unsetCustomUserId();

Singular.setDeviceCustomUserId("custom_user_id");

Implementação de Deep Links

As ligações profundas são ligações que abrem a aplicação no telemóvel do utilizador e o enviam diretamente para uma página ou experiência de utilizador específica, em vez de apenas para o widget principal da aplicação. As ligações profundas são normalmente utilizadas em campanhas de retargeting, destinadas a utilizadores que já têm a aplicação no seu telemóvel, mas que podem não ter interagido com ela durante algum tempo. O Singular suporta deep linking através de Singular Links.

Habilitando os Links Singulares

Para habilitar o Singular Links no iOS e no Android, consulte Pré-requisitos do Singular Links.

Para suporte ao Android, adicione o seguinte código no arquivo MainActivity.java do projeto:

import com.singular.flutter_sdk.SingularBridge;
import android.content.Intent;

@Override
protected void onNewIntent(@NonNull Intent intent) {
  super.onNewIntent(intent);
  SingularBridge.onNewIntent(intent);
}

import com.singular.flutter_sdk.SingularBridge;
import android.content.Intent;

override fun onNewIntent(intent: Intent) {
  super.onNewIntent(intent)
  SingularBridge.onNewIntent(intent);
}

Para suporte ao iOS, no AppDelegate.m do projeto, adicione o seguinte:

// Top of AppDelegate.m

            
#import "SingularAppDelegate.h"

- (BOOL)application:(UIApplication *)application 
     didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
       [GeneratedPluginRegistrant registerWithRegistry:self];
       [SingularAppDelegate shared].launchOptions = launchOptions;
       return [super application:application 
         didFinishLaunchingWithOptions:launchOptions];
}

- (BOOL)application:(UIApplication *)application 
     continueUserActivity:(NSUserActivity *)userActivity 
     restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> 
       *restorableObjects))restorationHandler {
         [[SingularAppDelegate shared] continueUserActivity:userActivity 
           restorationHandler:restorationHandler];
     return [super application:application continueUserActivity:userActivity 
         restorationHandler:restorationHandler ];
}

- (BOOL)application:(UIApplication *)app 
     openURL:(NSURL *)url 
     options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
       [[SingularAppDelegate shared] handleOpenUrl:url options:options];
       return [super application:app openURL:url options: options];
}

import singular_flutter_sdk
  
override func application(_ application: UIApplication, 
  didFinishLaunchingWithOptions
  launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    GeneratedPluginRegistrant.register(with: self) if 
      let singularAppDelegate = SingularAppDelegate.shared() {
        singularAppDelegate.launchOptions = launchOptions
      }
  return super.application(application, didFinishLaunchingWithOptions:launchOptions)
}

override func application(_ application: UIApplication, 
  continue userActivity:NSUserActivity, 
  restorationHandler: @escaping ([UIUserActivityRestoring]?)-> Void) -> Bool {
    if let singularAppDelegate = SingularAppDelegate.shared() {
      singularAppDelegate.continueUserActivity(userActivity, restorationHandler:nil)
    }
  return super.application(application, continue:userActivity, 
    restorationHandler: restorationHandler);
}

override func application(_ app: UIApplication, 
  open url: URL, options:[UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    if let singularAppDelegate = SingularAppDelegate.shared() {
      singularAppDelegate.handleOpen(url, options: options)
    }
  return super.application(app, open: url, options: options);
}

Manipulação de links do Singular

Use o mecanismo de manipulador do Singular para ler os detalhes do link de rastreamento que levou à abertura do aplicativo.

Por exemplo:

SingularConfig config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');

config.singularLinksHandler = (SingularLinkParams params) {
  String deeplink = params.deeplink;
  String passthrough = params.passthrough;
  bool isDeferred = params.isDeferred;
  // Add your code here to handle the deep link

};
          
Singular.init(config);

Eventos de rastreamento (não receita)

A Singular pode coletar dados sobre eventos in-app para ajudar a analisar o desempenho de suas campanhas e medir KPIs. Por exemplo, a sua organização pode querer recolher dados sobre logins de utilizadores, registos, conclusões de tutoriais ou subida de nível numa aplicação de jogos.

O Singular suporta uma variedade de eventos padrão. Esses eventos comumente usados são frequentemente suportados por redes de anúncios para relatórios e otimização. Outra vantagem é que, quando você usa nomes de eventos padrão, o Singular os reconhece automaticamente e os adiciona à lista Eventos sem que você precise defini-los manualmente. Recomendamos o uso de eventos padrão sempre que possível.

A lista de eventos enviados para a Singular (com os atributos que os acompanham) deve ser compilada pela equipa de UA/marketing/negócio com base nos KPIs de marketing da sua organização. A equipe de negócios pode seguir o guia em Como rastrear eventos no aplicativo: Guide For Singular Attribution Customers.

Com cada evento que rastreia, pode passar vários atributos. Veja os atributos padrão recomendados por evento.

Em seu código, envie eventos para o Singular usando os métodos event ou eventWithArgs.

Exemplo:

Singular.event(Events.sngLogin);
Singular.eventWithArgs(eventName, {attributeName:attributeValue});
Map<String, Object> map = HashMap<String, Object>();
map ['name'] = 'John Doe';
map ['age'] = 30;
map ['isStudent'] = false;
Singular.eventWithArgs('event_Name', map);

Rastreamento de receita

Envio de eventos IAP

Para permitir que a Singular rastreie quanta receita seu aplicativo está gerando, envie eventos IAP para a Singular. Ao enviar o evento IAP, você também permite que a Singular verifique os dados de verificação do evento e certifique-se de que não é fraudulento.

Veja o exemplo a seguir.

Observação: este snippet de código requer o pacote IAP do Flutter em https://pub.dev/packages/in_app_purchase.

import 'package:singular_flutter_sdk/singular_iap.dart';
import 'dart:io' show Platform;
            
// Parse the revenue amount and currency first
double revenue = double.tryParse(product.rawPrice.toStringAsFixed(2)) ?? 0.0;
String? currencyCode = product.currencyCode;

// Only process if both revenue is greater than 0 and currencyCode exists
if (revenue > 0 && currencyCode != null && currencyCode.isNotEmpty) {
  if (Platform.isIOS) {
    singularPurchase = new SingularIOSIAP(
      revenue,
      currencyCode,
      purchase.productID,
      purchase.purchaseID,
      purchase.verificationData.serverVerificationData
    );
  }
              
  else if (Platform.isAndroid) {
    singularPurchase = new SingularAndroidIAP(
      revenue,
      currencyCode,
      purchase.verificationData.serverVerificationData,
      purchase.verificationData.localVerificationData
    );
  }
              
  Singular.inAppPurchase(eventName, singularPurchase);
}

Método alternativo: Envio de eventos de receita personalizados

A Singular também oferece a opção de informar a receita enviando apenas um evento de receita personalizado com um nome e um valor de receita. Observe que esse método não compartilha o recibo de compra com o Singular e, portanto, não permite que o Singular verifique se é um evento legítimo.

Por exemplo:

Singular.customRevenue("MyCustomRevenue", "USD", 5.50);
Map<String, Object> map = HashMap<String, Object>();
map ['name'] = 'John Doe';
map ['age'] = 30;
map ['isStudent'] =false;
Singular.customRevenueWithAttributes('MyCustomRevenue','USD', 20, map);

Rastreamento de evento híbrido (avançado)

A Singular recomenda o envio de todos os eventos e receitas por meio do SDK da Singular integrado ao seu aplicativo. No entanto, a Singular pode coletar eventos e receitas de outras fontes.

Qualquer evento NÃO enviado do SDK da Singular deve estar em conformidade com os requisitos de documentação de eventos de servidor para servidor da Singular e fornecer o identificador de dispositivo correspondente para atribuir corretamente um evento.

Guias de rastreamento de eventos híbridos

Adição de suporte à atribuição de receita de anúncios

Adição de suporte a SKAdNetwork

Para ativar o rastreamento de SKAdNetwork para seu aplicativo, ative 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 em 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());
});

Outras opções

Rastreamento de desinstalações

Para permitir que o Singular rastreie desinstalações de aplicativos, forneça ao Singular o token APNS/FCM, como no exemplo a seguir:

// iOS

Singular.registerDeviceTokenForUninstall(apnsToken);
            
// Android

Singular.registerDeviceTokenForUninstall(fcmToken);

Conformidade com as leis de privacidade de dados

A Singular fornece a funcionalidade de proteção de privacidade para ajudá-lo a cooperar com quaisquer parceiros que possam estar em conformidade com as leis de privacidade do consumidor, como GDPR e CCPA(Lei de privacidade do consumidor da Califórnia). Estes parceiros querem ser notificados se o utilizador final consentiu em partilhar as suas informações privadas.

Se tiver implementado uma forma de pedir o consentimento dos utilizadores para partilharem as suas informações, utilize o método limitDataSharing para notificar a Singular da escolha do utilizador:

Utilize Singular.limitDataSharing(false) para indicar que o utilizador consentiu (opted in) em partilhar as suas informações.

Use Singular.limitDataSharing(true) se o usuário não consentiu.

A Singular utiliza LimitDataSharing em"User Privacy Postbacks", bem como transmite esta informação a parceiros que a requerem para cumprir os regulamentos relevantes. Consulte"Privacidade do utilizador e Limitar partilha de dados" para obter mais informações.

// User has opted into sharing data

Singular.limitDataSharing(false);

Métodos adicionais para conformidade com o GDPR

O Singular SDK fornece vários métodos para ajudá-lo a cumprir as políticas do GDPR e permitir que o Singular saiba sobre o consentimento ou não consentimento do usuário para rastreamento.

Singular.trackingOptIn();

Singular.stopAllTracking();

Singular.resumeAllTracking();

Singular.isAllTrackingStopped();