Integração SDK singular para flutter

 

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 pressupõe que você tenha um aplicativo Flutter funcional.
  • Para inicializar o SDK, você precisa da chave do SDK da Singular e do segredo do SDK. Você pode obtê-los na plataforma Singular em "Developer Tools > SDK Integration > SDK Keys".

Novo: Guia em vídeo

Assista a este vídeo para obter uma visão detalhada do processo de integração. Recomendamos usar tanto o vídeo quanto o guia escrito abaixo.

Integração do plug-in da Singular

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

dependencies:
  singular_flutter_sdk: ^1.4.0

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

flutter packages get

Etapas adicionais para Android

Adição de 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 da Singular requer a API do Google Mobile Ads, parte das APIs do Google Play Services 17.0.0+. Se você já integrou o Google Play Services ao seu aplicativo, o requisito foi atendido. Caso contrário, você poderá integrar o Google Mobile Ads individualmente, incluindo a seguinte dependência no build.gradle do seu aplicativo:

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

Se você tiver desativado as dependências transitivas para o Singular SDK, adicione o seguinte ao build.gradle do seu aplicativo.

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

Observação: se for apresentado um erro de DuplicateClasses no momento da compilação, talvez você já tenha o Google play-services e possa comentar a dependência.

Adição de permissões

Adicione essas permissões sob a tag <manifest> em 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" />

Se a compilação do seu aplicativo tiver como alvo o Android 12/API nível 31 ou superior, adicione permissões para acessar o ID de publicidade do Google:

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

Observação: não adicione essa permissão se estiver integrando o Kids SDK.

Cuidado: Se o seu aplicativo tiver a permissão android.permission.GET_TASKS, o aplicativo poderá ser inicializado antes que o usuário realmente o abra. Isso pode inicializar o Singular SDK e causar discrepâncias no tempo de instalação. Para evitar o problema, remova a permissão se ela não for necessária ou mova a chamada de inicialização do Singular SDK para outro lugar no código, garantindo que ela seja chamada somente depois que o usuário abrir o aplicativo pela primeira vez.

Etapas adicionais para iOS

Para usar o plug-in do Singular, você precisa adicionar a estrutura do AdServices.

Inicialização do SDK do Singular

O código de inicialização do Singular SDK deve ser chamado toda vez 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 para o widget principal do aplicativo (ou seja, main.dart) - o primeiro que é carregado quando o aplicativo é aberto. Esse widget deve ter estado, e o código deve ser adicionado ao método initState() do widget.

  1. Primeiro, você precisa criar um objeto SingularConfig. O objeto contém sua chave e segredo do Singular SDK.
  2. Opcionalmente, você pode adicionar configurações para ativar vários recursos do SDK. Veja a lista completa de opções.
  3. Suporte à atribuição de referenciador da instalação META

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

    1. Forneça seu Facebook App Id no objeto de configuração Singular.
      // Para ativar o referenciador de instalação META
      config.facebookAppId = "INSIRA SEU ID DO APLICATIVO DO FACEBOOK AQUI";
    Onde posso encontrar o Facebook App ID 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'); // Definir ID de usuário com hash, se disponível
config.customUserId = "b642b4217b34b1e8d3bd915fc65c4452";

// Para iOS (remova se não estiver exibindo um prompt ATT)!
config.waitForTrackingAuthorizationWithTimeoutInterval = 300;

// Para ativar o referenciador de instalação META
config.facebookAppId = "INSIRA SEU ID DO APLICATIVO DO FACEBOOK AQUI";

// Para ativar o suporte SkAdNetwork
config.skAdNetworkEnabled = true;

/* (opcional) Usando o recurso Propriedades Globais Singulares para capturar identificadores de terceiros. O(s) respectivo(s) SDK(s) devem ser inicializados antes do SDK Singular. Exemplo de passagem do CleverTapID.*/
// var cleverTapId = CleverTapPlugin.getCleverTapID();
// config.withGlobalProperty("CLEVERTAPID", cleverTapId, true);
Singular.start(config); }

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

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

Observação: se você usar a solução Cross-Device da Singular, deverá coletar a ID de usuário em todas as plataformas.

  • O ID do usuário pode ser qualquer identificador e não deve expor PII (Informações Pessoais Identificáveis). Por exemplo, você não deve usar o endereço de e-mail, nome de usuário ou número de telefone de um usuário. A Singular recomenda o uso de um valor hash exclusivo apenas para seus dados primários.
  • O valor do ID de usuário passado para a Singular também deve ser o mesmo ID de usuário interno que você captura em todas as plataformas (Web/Mobile/PC/Console/Offline).
  • A Singular incluirá o ID de usuário nas exportações em nível de usuário, ETL e postbacks de BI interno (se configurado). O ID do usuário é um dado primário, e a Singular não o compartilha com terceiros.
  • O valor da ID de usuário, quando definido com o método Singular SDK, persistirá até que seja desfeito usando o método unsetCustomUserId ou até que o aplicativo seja desinstalado. O fechamento ou a reinicialização do aplicativo não desinstala a ID de usuário.

Para definir a ID de usuário, use o método setCustomUserId. Para cancelar a definição (por exemplo, se o usuário fizer "logout" da conta), ligue para unsetCustomUserId.

Observação: se vários usuários usarem um único dispositivo, recomendamos a implementação de um fluxo de logout para definir e cancelar a definição da ID de usuário para cada login e logout.

Se você já souber a ID do usuário quando o aplicativo for aberto, ligue para setCustomUserId antes de inicializar o SDK da Singular. Dessa forma, a 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.

Método Singular.setCustomUserID
Descrição Envia o ID do usuário para a Singular.
Assinatura static void setCustomUserId(String customUserId)
Exemplo de uso
Singular.setCustomUserId("custom_user_id");
Método Singular.unsetCustomUserID
Descrição Desfaz a definição do ID de usuário que foi enviado à Singular.
Assinatura static void unsetCustomUserId()
Exemplo de uso
Singular.unsetCustomUserId();

Opcional: Mapeamento do dispositivo de ID de usuário personalizado

Importante: esse recurso avançado da Enterprise só está disponível em casos excepcionais. Consulte um dos engenheiros de soluções da Singular antes de implementá-lo.

A Singular pode receber dados adicionais de rastreamento de eventos móveis por meio de uma integração de servidor para servidor. Para utilizar esse recurso, você deve mapear o ID do usuário para o identificador de rastreamento de dispositivos móveis da Singular.

Observação: chame esse método o mais rápido possível após a inicialização do SDK da Singular ou assim que tiver o ID do usuário.

Método Singular.setDeviceCustomUserId
Descrição Define o ID de usuário personalizado igual ao login e o mapeia para o identificador de rastreamento da Singular.
Assinatura static void setDeviceCustomUserId(String customUserId)
Exemplo de uso
Singular.setDeviceCustomUserId("custom_user_id");

Implementação de Deep Links

Deep links são links que abrem o aplicativo no telefone do usuário e o enviam diretamente para uma página ou experiência de usuário específica, em vez de apenas para o widget principal do aplicativo. Os deep links geralmente são usados em campanhas de retargeting, voltadas para usuários que já têm o aplicativo no celular, mas talvez não tenham se envolvido com ele por algum tempo. A Singular suporta deep linking por meio de Singular Links.

Ativação de Singular Links

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

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

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

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

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

 

Objective-C Swift
// 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]; }

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; // Adicione seu código aqui para lidar com o link direto }; Singular.init(config);

Rastreamento de eventos (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, sua organização pode querer coletar dados sobre logins de usuários, registros, conclusões de tutoriais ou subida de nível em um aplicativo de jogos.

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

A lista de eventos enviados à Singular (com os atributos que os acompanham) deve ser compilada pela equipe de UA/marketing/negócios com base nos KPIs de marketing da sua organização. A equipe de negócios pode seguir o guia em How to Track In-App Events: Guide For Singular Attribution Customers (Guia para clientes de atribuição singular).

Com cada evento que você rastreia, é possível passar vários atributos. Veja os atributos padrão recomendados por evento.

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

Observação: para eventos padrão, use o nome Flutter do evento como ele aparece na Lista de eventos e atributos padrão do Flutter SDK, por exemplo, sngLogin.

Para eventos personalizados, eventos que sua organização deseja medir e que não correspondem a nenhum dos eventos padrão da Singular, use qualquer nome personalizado (máximo de 32 caracteres). Recomendamos o uso de nomes em inglês para compatibilidade com quaisquer parceiros de rede de anúncios que possam receber o evento da Singular para fins de otimização.

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 a quantidade de receita que 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 sejam fraudulentos.

Veja o exemplo a seguir.

Observação: esse trecho 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;
            
if (Platform.isIOS) {
  singularPurchase = new SingularIOSIAP(
    product.rawPrice.toStringAsFixed(2),
    product.currencyCode,
    purchase.productID,
    purchase.purchaseID,
    purchase.verificationData.serverVerificationData
  );
}
            
else if (Platform.isAndroid) {
  singularPurchase = new SingularAndroidIAP(
    product.rawPrice.toStringAsFixed(2),
    product.currencyCode,
    purchase.verificationData.serverVerificationData,
    purchase.verificationData.localVerificationData
  );
}
            
Singular.inAppPurchase(eventName, singularPurchase);

Observação: passe a moeda como um código de moeda ISO 4217 de três letras, por exemplo, "USD", "EUR", "INR".

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 a Singular e, portanto, não permite que a 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);

Observação: passe a moeda como um código de moeda ISO 4217 de três letras, por exemplo, "USD", "EUR", "INR".

Rastreamento híbrido de eventos (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 pelo 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.

Importante:

Ocorrerão discrepâncias se os identificadores de dispositivo usados nas solicitações de eventos Server-to-Server não tiverem um identificador de dispositivo correspondente no Singular. Esteja ciente das seguintes possibilidades:

  • Se uma solicitação de evento for recebida "antes" de o SDK do Singular ter registrado o identificador do dispositivo, a partir de uma sessão de aplicativo, a solicitação de evento será considerada a "primeira sessão" do dispositivo desconhecido, e o Singular atribuirá o dispositivo como uma atribuição orgânica.
  • Se o Singular SDK tiver registrado um identificador de dispositivo, mas o identificador do Singular SDK for diferente do identificador de dispositivo especificado na solicitação de evento de servidor para servidor, o evento será atribuído incorretamente.

Guias de rastreamento de eventos híbridos

Envio de eventos de um servidor interno

A Singular pode coletar dados sobre a receita de seu servidor para ajudar a analisar o desempenho e o ROI de suas campanhas.

Requisitos:

  • A partir de um evento de registro ou login no aplicativo, capture e passe os identificadores de dispositivo e armazene esses dados com o ID do usuário no seu servidor. Como os identificadores de dispositivo podem mudar para um usuário, certifique-se de atualizar os identificadores quando um usuário gerar uma sessão de aplicativo. Isso garante que o evento no lado do servidor será atribuído ao dispositivo correto.
  • Os eventos do lado do servidor são específicos da plataforma e só devem ser enviados com o identificador de dispositivo correspondente à plataforma do dispositivo (por exemplo, IDFA ou IDFV para dispositivos iOS).
  • Você pode usar o mecanismo de postback do Singular Internal BI para enviar um evento em tempo real para seu endpoint interno, de modo que possa atualizar o conjunto de dados no lado do servidor. Consulte as Perguntas frequentes sobre postback do BI interno.
  • Consulte a seção "Rastreamento de receita" no guia Integração servidor a servidor para obter detalhes.
Envio de eventos de um provedor de receita
Provedores de terceiros, como RevenueCat ou adapty, podem fornecer receita de compra e assinatura para a Singular.

Siga os links abaixo para obter detalhes sobre como habilitar esses parceiros.

Envio de eventos do segmento

Para permitir que o Segment envie eventos para a Singular, em paralelo com o SDK da Singular, você deve adicionar um destino "Cloud-Mode" no Segment. Siga nosso guia AQUI.

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

Você pode configurar a atribuição de receita de anúncios por meio do Singular SDK.

Para adicionar suporte à atribuição de receita de anúncios usando o SDK do Flutter:

  1. Adicione o snippet de código apropriado para obter informações de receita de anúncios da plataforma de mediação que você usa para dados de receita de anúncios.

    Consulte os trechos de código em nossa documentação do Android SDK.

Observação: passe a moeda como um código de moeda ISO 4217 de três letras, por exemplo, "USD", "EUR", "INR".

Informe os eventos de receita de anúncios à Singular usando o seguinte código
  1. Inicialize o objeto SingularAdData com os dados relevantes
  2. Informar os dados à Singular
Dart
SingularAdData adData = SingularAdData(
"SUA_PLATAFORMA_DE_ANÚNCIOS",
"CÓDIGO DA MOEDA",
0.05) Singular.adRevenue(adData)

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, a Singular gerencia automaticamente o valor de conversão da 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 Singulare 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.

Observação: o modo SKAN Managed já está ativado no trecho de código de inicialização acima.Certifique-se de que você tenha definido esses itens de configuração.

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 você já tiver sua própria estratégia e ferramentas para gerenciar o valor de conversão da SKAdNetwork, poderá 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);

Em seguida, para atualizar o valor de conversão, use o seguinte código:

ingular.skanUpdateConversionValue(conversionValue)

Para rastrear quando o valor de conversão for alterado, use 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, use o código a seguir:

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

Outras opções

Rastreamento de desinstalações

Para permitir que o Singular rastreie as 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 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(California Consumer Privacy Act). Esses parceiros querem ser notificados se o usuário final consentiu em compartilhar suas informações privadas.

Se você tiver implementado uma forma de solicitar o consentimento dos usuários para compartilhar suas informações, use o método limitDataSharing para notificar a Singular sobre a escolha do usuário:

Use Singular.limitDataSharing(false) para indicar que o usuário consentiu (optou por participar) em compartilhar suas informações.

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

A Singular usa LimitDataSharing em "Postbacks de privacidade do usuário", bem como repassa essas informações a parceiros que as exigem para cumprir os regulamentos relevantes. Consulte "Privacidade do usuário e Limite de compartilhamento de dados" para obter mais informações.

Observação: o uso do método é opcional, mas pode haver informações de atribuição que o parceiro compartilhará com a Singular somente se for especificamente notificado de que o usuário optou por participar.

Método Singular.limitDataSharing
Assinatura Singular.limitDataSharing(booleanshouldLimitDataSharing)
Descrição Notifica a Singular sobre o consentimento do usuário (opt-in) para o compartilhamento de dados privados.
Exemplo de uso
// O usuário optou por compartilhar dados
Singular.limitDataSharing(false);

Métodos adicionais para conformidade com o GDPR

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

Método Singular.trackingOptIn
Descrição Notifica a Singular sobre o consentimento do usuário (opt-in) para rastreamento.
Exemplo de uso
Singular.trackingOptIn();
Método Singular.stopAllTracking
Descrição

Interrompe todas as atividades de rastreamento para este usuário neste aplicativo.

Observação: a chamada desse método desativa efetivamente o SDK, mesmo após a reinicialização do aplicativo (o estado é persistente)! A única maneira de reativar o rastreamento é chamar resumeAllTracking().
Exemplo de uso
Singular.stopAllTracking();
Método Singular.resumeAllTracking
Descrição Retoma o rastreamento para esse usuário neste aplicativo.
Exemplo de uso
Singular.resumeAllTracking();
Método Singular.isAllTrackingStopped
Descrição Verifica o status de rastreamento desse usuário nesse aplicativo. Retorna true se o rastreamento tiver sido interrompido usando StopAllTracking() e não tiver sido retomado.
Exemplo de uso
Singular.isAllTrackingStopped();