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

Siga as etapas em Integração de um SDK Singular:Planejamento e pré-requisitos.

Essas etapas são pré-requisitos para qualquer integração do Singular SDK.

1. Adicionando o SDK ao seu projeto

1.1 Adição do SDK usando o Gradle

1. Adicione o repositório Singular SDK ao arquivo settings.gradle:

   dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
             google()
             mavenCentral()
             maven { url 'https://maven.singular.net/' }
        }
   }

   OU em versões mais antigas do Gradle, adicione o repositório do Singular SDK ao arquivo project/build.gradle:

   repositories {
           mavenCentral()
           maven { url 'https://maven.singular.net/' }
       }

2. Adicione a biblioteca Singular à lista de dependências em app/build.gradle:

   dependencies {
       implementation 'com.google.android.gms:play-services:6.5.87'
       implementation fileTree(dir: 'libs', include: ['*.jar'])
       ...
       implementation 'com.singular.sdk:singular_sdk:12.6.0'
       ...
   }

   Além disso, adicione o seguinte para dar suporte ao referenciador de instalação da Samsung Galaxy Store se seu aplicativo for distribuído por meio da Samsung Galaxy Store:

   dependencies {
         ...
         implementation 'store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:4.0.0'
         ...
       }

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

   dependencies {
       ...
       implementation 'com.android.installreferrer:installreferrer:2.2'
       implementation 'com.google.android.gms:play-services-appset:16.0.0'
       ...
   }

4. Se o seu aplicativo não implementar a API 17.0.0 ou superior do Google Play Services , adicione a seguinte dependência ao arquivo app/build.gradle:

   dependencies {
        ...
        implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0+'
        ...
   }

1.2. Adicionando o SDK sem o Gradle

<project ...>
<repositories>
    <repository>
      <id>singular.net</id>
      <url>http://maven.singular.net/</url>
    </repository>
 </repositories>
</project>

<dependency>
    <groupId>com.singular.sdk</groupId>
    <artifactId>singular_sdk</artifactId>
    <version>12.0.2</version>
</dependency>

-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
# Descomente esta linha caso esteja chamando a função 'revenue' usando a biblioteca de faturamento do Google
#-keep public class com.android.billingclient.** { *; }

1.3. Adição de permissões necessárias

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

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

Além disso, adicione o seguinte para dar suporte ao referenciador de instalação da Samsung Galaxy Store se o seu aplicativo for distribuído por meio da Samsung Galaxy Store e tiver como alvo o Android 11 ou superior:

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

Além disso, adicione o seguinte para dar suporte ao referenciador de instalação da Samsung Galaxy Store se o seu aplicativo for distribuído por meio da Samsung Galaxy Store e tiver como alvo o Android 11 ou superior:

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

2. Configuração de uma integração básica do SDK

2.1. Importação da biblioteca da Singular

Para importar a biblioteca Singular, adicione a seguinte importação ao seu arquivo MainActivity:

import com.singular.sdk.*;

import com.singular.sdk.*

2.2. Construção de um objeto de configuração

Antes de inicializar o SDK, você precisa criar um objeto SingularConfig. Esse objeto conterá o seguinte:

1. Chaves SDK e segredos SDK (para obtê-los, faça login em sua conta Singular e acesse "DEVELOPER TOOLS > SDK Integration > SDK Keys").
2. Opcionalmente, quaisquer preferências de SDK que você queira definir.
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.withFacebookAppId("INSIRA SEU ID DO APLICATIVO DO FACEBOOK AQUI");

   Onde posso encontrar o Facebook App ID de um aplicativo?

O exemplo de código a seguir cria um objeto de configuração e define as opções de configuração comuns antes de inicializar o SDK da Singular.

As seções a seguir fornecem mais detalhes sobre essas opções e como você pode personalizá-las.

@Override
protected void onCreate(Bundle savedInstanceState) {
    ...
    // Criar um objeto de configuração
    SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");

    // Configurar um manipulador de deep links
    config.withSingularLink(
        getIntent(), 
        new SingularLinkHandler() {
            @Override
            public void onResolved(SingularLinkParams params) {
                String deeplink = params.getDeeplink();
                String passthrough = params.getPassthrough();
                boolean isDeferred = params.isDeferred();

                // Adicione o código de tratamento de links diretos aqui
            }
        }
    );

    Singular.init(context, config);
    
    ...
}

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Criar um objeto de configuração
    val config = SingularConfig("SDK KEY", "SDK SECRET")

    // Configurar um manipulador de deep links
    config.withSingularLink(
        intent
    ) { params ->
        val deeplink = params.deeplink
        val passthrough = params.passthrough
        val isDeferred = params.isDeferred

        // Adicione o código de tratamento de links diretos aqui
    }

    Singular.init(this, config)

    ...
}

2.3. Adição de suporte a Deep Linking

Deep links são links que levam a um conteúdo específico dentro de um aplicativo. Quando um usuário clica em um link profundo em um dispositivo com o aplicativo instalado, o aplicativo é aberto e mostra um produto ou uma experiência específica. Os links de rastreamento singulares podem incluir links diretos, bem como links diretos adiados(consulte nossas Perguntas frequentes sobre links diretos e as Perguntas frequentes sobre links singulares para obter mais informações).

Ativação de deep links usando links singulares

Para ativar links diretos para seu aplicativo, consulte Pré-requisitos de links singulares.

Adição de um filtro de intenção de links diretos

Adicione um filtro de intenção como o seguinte ao AndroidManifest.xml para ativar o suporte a deep links em uma atividade. Se você tiver mais de uma atividade que deva ser aberta por meio de um deep link, faça isso para cada atividade.

<activity> 
    <intent-filter>
        <data android:scheme="singular-example" />
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
    </intent-filter>
</activity>

Manipulação de deep links

O Singular SDK fornece um mecanismo de manipulação para ler os detalhes do link de rastreamento que levou à abertura do aplicativo. Um exemplo de manipulador está incluído acima no código de exemplo para Construção de um Objeto de Configuração.

Modificação do tempo limite do Deferred Deep Link

Por padrão, quando um aplicativo envia a primeira sessão para o Singular de um determinado dispositivo, o servidor Singular procura em seus registros se há um deferred deep link que corresponda a esse dispositivo (consulte O que são deferred deep links?). Se um deferred deep link for encontrado, ele será enviado de volta ao aplicativo para processamento. Mas se nenhum deferred deep link for encontrado em 60 segundos, o servidor interrompe a pesquisa.

Você pode modificar o valor do tempo limite chamando withDDLTimeoutInSec ao criar o objeto SingularConfig. O exemplo abaixo altera o tempo limite para 30 segundos:

SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");
...
config.withDDLTimeoutInSec(30);
...
Singular.init(context, config);

Manuseio de deep links não-singulares

O Singular SDK oferece suporte a deep links não-singulares. Isso é necessário para medir a atribuição para parceiros como o Google Ads.

A partir da versão 12.1.1 do SDK do Android, os Universal Links que não são da Singular são compatíveis por padrão. Não é necessária nenhuma ação de sua parte para oferecer suporte a links de terceiros se você tiver a nova versão do SDK.

SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");

// supportedDomains
List<String> supportedDomains = Arrays.asList("subdomain.mywebsite.com", "subdomain.myotherwebsite.com");
config.withSingularLink(
    getIntent(), 
    new SingularLinkHandler() {
        @Override
        public void onResolved(SingularLinkParams params) {
            // manipular retorno de chamada
        }
    }, 
    supportedDomains
);

2.4. Inicialização do Singular

O SDK da Singular deve ser inicializado toda vez que seu aplicativo for aberto. Esse é um pré-requisito para todas as funcionalidades de atribuição da Singular e também envia uma nova sessão de usuário para a Singular (as sessões são usadas para calcular a retenção de usuários).

Para inicializar o Singular, use o código a seguir:

Singular.init(context, config);

O método init pode ser chamado em qualquer ponto do aplicativo, mas deve ser chamado antes que qualquer evento seja relatado. Recomendamos chamar init no onCreate da atividade principal, bem como em qualquer atividade que será aberta diretamente por um deep link.

2.5. 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.

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

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.

Singular.setCustomUserId("custom_user_id");

Singular.unsetCustomUserId();

Singular.setDeviceCustomUserId("custom_user_id");

2.6. Implementação de propriedades globais (opcional)

O SDK da Singular permite que você defina propriedades personalizadas adicionais para enviar aos servidores da Singular com cada sessão e evento enviado pelo aplicativo. Essas propriedades podem representar qualquer informação que você queira sobre o usuário, o modo ou o status do aplicativo ou qualquer outra coisa.Depois de definir essas propriedades, elas ficam disponíveis como dimensões em seus relatórios e você pode usá-las para dividir seus dados.

Por exemplo, se você tiver um aplicativo de jogos, poderá definir uma propriedade chamada "Nível" e configurá-la inicialmente como "0". Qualquer sessão e evento enviado pelo aplicativo será enviado com "Level": "0". Quando o usuário subir de nível, redefina a propriedade para "1" e assim por diante. Em seguida, você poderá obter seus relatórios, incluindo sessões, contagens de eventos e dados de receita, divididos por nível de usuário.

• Você pode definir até 5 propriedades globais.
• Elas persistem entre as execuções do aplicativo (com o valor mais recente que você lhes deu) até que você as desfaça ou o usuário desinstale o aplicativo.
• Cada nome e valor de propriedade pode ter até 200 caracteres. Se você passar um nome ou valor de propriedade mais longo, ele será truncado em 200 caracteres.
• As propriedades globais são acessíveis e estão disponíveis em exportações e postbacks no nível do usuário. No futuro, será adicionado o suporte a relatórios agregados. Informe seu gerente de sucesso do cliente Singular se tiver alguma dúvida ou se estiver interessado em atualizações do suporte a propriedades globais!

Configuração de propriedades globais por meio do SingularConfig

Você pode usar o método withGlobalProperty para definir propriedades globais por meio do SingularConfig antes de inicializar o SDK.

Observe que, como as propriedades globais e seus valores persistem entre as execuções do aplicativo, a propriedade que você está definindo pode já estar definida com um valor diferente. Use o parâmetro overrideExisting para informar ao SDK se deve substituir uma propriedade existente pelo novo valor ou não.

// Defina duas propriedades globais e substitua os valores existentes
SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET")
  .withGlobalProperty(“MyProperty”, “MyValue”, true)
  .withGlobalProperty(“AnotherProperty”, “AnotherValue”, true);

Definição de propriedades globais após a inicialização

Use os métodos a seguir para definir, cancelar a definição e recuperar propriedades globais a qualquer momento durante a execução do aplicativo.

boolean result = Singular.setGlobalProperty(“MyProperty”, “MyValue”, true);

Map<String, String> map = Singular.getGlobalProperties();

Singular.unsetGlobalProperty(“MyProperty”);

Singular.clearGlobalProperties();

3. Rastreamento de eventos e receita

3.1. 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 aumento de nível em um aplicativo de jogos.

O que são eventos e atributos padrão?

A Singular oferece suporte a uma variedade de eventos padrão.Outra vantagem é que ,quando você usa nomes de eventos padrão, o 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 rastreado, você pode passar vários atributos. Veja os atributos padrão recomendados por evento.

Envio de eventos

Em seu código, envie eventos para a Singular usando os métodos eventJSON ou event (recomendamos o eventJSON para facilitar a leitura).

• Para eventos padrão, use o nome Android do evento como ele aparece na lista de eventos e atributos padrão do Android SDK, por exemplo, sngTutorialComplete. Veja os exemplos de código abaixo.
• Se você enviar quaisquer eventos personalizados (eventos que sua organização deseja medir e que não correspondem a nenhum dos eventos padrão do Singular), use qualquer cadeia de caracteres que desejar e que esteja em conformidade com as limitações.

// Exemplo 1: envie o evento padrão sng_tutorial_complete com os atributos padrão recomendados.
JSONObject att = new JSONObject();
att.put(Attributes.sngAttrContent.toString(), <TUTORIAL NAME>);
att.put(Attributes.sngAttrContentId.toString(), <CONTENT ID>);
att.put(Attributes.sngAttrContentType.toString(), <TYPE OF CONTENT>);
att.put(Attributes.sngAttrSuccess.toString(), <LOGIN SUCCESS VALUE>);

Singular.eventJSON(Events.sngTutorialComplete.toString(), att);

// Exemplo 2: Envie um evento personalizado chamado "bonus_points_earned" com um atributo personalizado.
JSONObject att = new JSONObject();
att.put("Points", 500);
Singular.eventJSON("Bonus Points Earned", att);

// Exemplo 1: envie o evento padrão sng_tutorial_complete com os atributos padrão recomendados.
val att = new JSONObject()
att.put(Attributes.sngAttrContent.toString(), "TUTORIAL NAME")
att.put(Attributes.sngAttrContent.toString(), "CONTENT ID")
att.put(Attributes.sngAttrContent.toString(), "TYPE OF CONTENT")
att.put(Attributes.sngAttrContent.toString(), "LOGIN SUCCESS VALUE")

Singular.eventJSON(Events.sngTutorialComplete.toString(), att)

// Exemplo 2: Envie um evento personalizado chamado "bonus_points_earned" com um atributo personalizado.
val att = new JSONObject()
att.put("Points", 500)
Singular.eventJSON("Bonus Points Earned", att)

// Exemplo 1: envie o evento padrão sng_tutorial_complete com os atributos padrão recomendados.
Singular.event(Events.sngTutorialComplete.toString(),
  Attributes.sngAttrContent.toString(), <TUTORIAL NAME>,
  Attributes.sngAttrContentId.toString(), <CONTENT ID>,
  Attributes.sngAttrContentType.toString(), <TYPE OF CONTENT>,
  Attributes.sngAttrSuccess.toString(), <SUCCESS>
);

// Exemplo 2: enviar o evento padrão "Subscribe" (sng_subscribe), sem atributos.
Singular.event(Events.sngSubscribe.toString());

// Exemplo 3: Envie um evento personalizado chamado "bonus_points_earned" com um atributo personalizado.
Singular.event("Bonus Points Earned", "Points", 500);

// Exemplo 1: envie o evento padrão sng_tutorial_complete com os atributos padrão recomendados.
Singular.event(Events.sngTutorialComplete.toString(),
  Attributes.sngAttrContent.toString(), "TUTORIAL NAME",
  Attributes.sngAttrContentId.toString(), "CONTENT ID",
  Attributes.sngAttrContentType.toString(), "TYPE OF CONTENT",
  Attributes.sngAttrSuccess.toString(), "SUCCESS"
)

// Exemplo 2: enviar o evento padrão "Subscribe" (sng_subscribe), sem atributos.
Singular.event(Events.sngSubscribe.toString())

// Exemplo 3: Envie um evento personalizado chamado "bonus_points_earned" com um atributo personalizado.
Singular.event("Bonus Points Earned", "Points", 500)

3.2. Rastreamento de receita

A Singular pode coletar dados sobre a receita obtida por meio do aplicativo para ajudar a analisar o desempenho e o ROI de suas campanhas. A Singular disponibilizará os dados para você em relatórios, exportação de registros e postbacks.

Rastreamento de receita usando o objeto Purchase

Ao relatar eventos de receita para a Singular, recomendamos que você passe o objeto de compra recebido da biblioteca de faturamento. Isso tem duas vantagens:

1. A Singular obtém todos os detalhes da transação, o que enriquece seus relatórios da Singular.
2. A Singular obtém o recibo da transação do Google, que pode ser usado para validar a transação no contexto do combate à fraude no aplicativo.

Use os métodos revenue e customRevenue para relatar eventos. O CustomRevenue permite que você passe um nome de evento personalizado, para que você possa visualizar a receita nos relatórios da Singular dividida pelos diferentes tipos de eventos de receita.

Observação: qualquer receita informada em uma moeda diferente será convertida automaticamente para a moeda preferencial de sua organização, conforme definido em sua conta do Singular.

// Envie um evento de receita para o Singular + o objeto de compra que 
// foi recebido da Biblioteca de faturamento do Google. 
Singular.revenue("USD", 5.50, purchase);

// Envia um evento de receita para a Singular, passando o nome do evento e o objeto de compra.
Singular.customRevenue("MyCustomRevenue", "USD", 
    5.50, purchase);

Relatório de receita sem o objeto Purchase

Embora seja altamente recomendável relatar eventos de receita da maneira descrita acima, você também pode usar revenue e customRevenue sem passar o objeto de compra. Em vez disso, você passa a moeda e o valor da transação, além de detalhes opcionais do produto.

Observe que, ao relatar eventos de receita dessa forma, a Singular não obtém o recibo de compra e não pode validar a transação.

// Enviar um evento de receita para a Singular com detalhes do produto
Singular.revenue("EUR", 5.00, "SKU1928375", 
"Reservation Fee", "Fee" , 1, 5.00);

// Enviar um evento de receita para a Singular sem detalhes do produto
Singular.revenue("USD", 5.50);

// Envie um evento de receita para a Singular com o nome do evento 
// e os detalhes do produto.
Singular.customRevenue("MyCustomRevenue", "EUR", 5.00, 
"SKU1928375", "Reservation Fee", "Fee" , 1, 5.00);

// Enviar um evento de receita para a Singular com o nome do evento
Singular.customRevenue("MyCustomRevenue", "USD", 5.50);

3.3. 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.

Guias de rastreamento de eventos híbridos

4. Opções avançadas

4.1. Criação de links de referência curtos

Observação: essa funcionalidade está disponível na versão 12.1.1+ do SDK. Depois de criados, os links curtos permanecem ativos por 30 dias.

Use links curtos para transformar links singulares longos e cheios de parâmetros em links mais curtos e mais seguros que sejam convenientes para compartilhamento.

Normalmente, você deseja criar links curtos dinamicamente para que os usuários do seu aplicativo possam compartilhá-los com amigos e convidá-los a usar o aplicativo.

Para criar um link curto, você precisa de:

• Um Singular Link que leve ao download do aplicativo (consulte as Perguntas frequentes sobre Singular Links).
• Quaisquer parâmetros que você queira adicionar ao link dinamicamente (consulte Parâmetros do link de rastreamento para obter a lista de opções).
• O nome e o ID do usuário de referência, se você quiser rastrear as novas instalações do aplicativo até o usuário que compartilhou o link.

Use o método createReferrerShortLink para criar um link curto, como no exemplo abaixo.

// Crie um objeto JSON para adicionar parâmetros ao Singular Link (se eles ainda não existirem no URL do link)
JSONObject params = new JSONObject();       
try {
      params.put("channel","sms");
      params.put("another parameter","parameter value");
} catch (JSONException e) {
      e.printStackTrace();
}

Singular.createReferrerShortLink (
  "https://sample.sng.link/D52wc/cuvk?pcn=test", // O URL original do Singular Link
  "Referrer Name",
  "Referrer ID",
  params,
  new ShortLinkHandler() { 
    @Override
      public void onSuccess(final String shortLinkURL) {
        view.post(new Runnable() {
          @Override
          public void run() {
            // Adicione sua lógica de compartilhamento aqui
          }   
        });
      }

    @Override
    public void onError(final String error) {  
      view.post(new Runnable() {    
        @Override
        public void run() { 
          // Lógica para tentar novamente/abortar/modificar os parâmetros passados para a função, com base na causa do erro.
        }
      });
    }
});

// Crie um objeto JSON para adicionar parâmetros ao Singular Link (se eles ainda não existirem no URL do link)
val params = JSONObject()
try {
    params.put("channel", "sms")
    params.put("another parameter", "parameter value")
} catch (e: JSONException) {
    e.printStackTrace()
}

Singular.createReferrerShortLink(
    "https://sample.sng.link/D52wc/cuvk?pcn=test",  // O URL original do Singular Link
    "Referrer Name",
    "Referrer ID",
    params,
    object : ShortLinkHandler {
        override fun onSuccess(shortLinkURL: String) {
            view.post(Runnable {
                // Adicione sua lógica de compartilhamento aqui
            })
        }

        override fun onError(error: String) {
            view.post(Runnable {
                // Lógica para tentar novamente/abortar/modificar os parâmetros passados para a função, com base na causa do erro.
            })
        }
    })

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

4.3. Rastreamento de desinstalação

Para ativar o rastreamento de desinstalação para seu aplicativo Android, primeiro configure o aplicativo na plataforma Singular, conforme detalhado em Configuração do rastreamento de desinstalação. Em seguida, siga as instruções abaixo.

I. Integrar com o FCM:

Para rastrear desinstalações, você pode usar os serviços da plataforma Firebase Cloud Messaging (FCM). Se ainda não estiver usando o FCM, siga as instruções do Google sobre como configurar um aplicativo cliente do Firebase Cloud Messaging no Android.

Requisitos do FCM ( fonte )

Os clientes FCM exigem dispositivos com Android 4.1 ou superior que também tenham o aplicativo Google Play Store instalado ou um emulador com Android 4.1 com APIs do Google. Observe que você não está limitado a implantar seus aplicativos Android por meio da Google Play Store.

Os usuários/dispositivos que não estiverem executando versões compatíveis do Android não estarão disponíveis para o rastreamento de desinstalação da Singular.

II. Atualize o arquivo AndroidManifest.xml:

Atualize seu arquivo AndroidManifest.xml para adicionar o filtro de intenção necessário para seu aplicativo (substitua MyFirebaseMessagingService por sua classe que implementa o Firebase Service):

<service android:name=".java.MyFirebaseMessagingService"
android:exported="false">
    <intent-filter>
        action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

III. Registre e envie o token de dispositivo FCM:

Por fim, defina o token do dispositivo FCM depois que o SingularConfig for inicializado em OnCreate(), como segue:

Singular.setFCMDeviceToken(String fcmDeviceToken);

4.4. Coleta do referenciador de instalação em dispositivos mais antigos

Observação: o Google está descontinuando a transmissão da intenção install_referrer. Veja: Ainda está usando o InstallBroadcast? Mude para a API Play Referrer até 1º de março de 2020

O referenciador de instalação é a ferramenta mais precisa da Singular para determinar a atribuição, além de ajudar a Singular a detectar e analisar tentativas de fraude. É um identificador fornecido pela Google Play Store que aponta para o anúncio no qual o usuário clicou antes de instalar o aplicativo.

Em dispositivos que possuem a versão mais recente da Google Play Store, o SDK da Singular coleta o valor do referenciador de instalação automaticamente (já que a Singular está integrada à API de referenciador da Google Play mais recente).

Para coletar o referenciador de instalação em dispositivos mais antigos:

Se você tiver um receptor de referenciador de instalação existente:

É provável que seu aplicativo já tenha um BroadcastReceiver que recebe o INSTALL_REFERRER do Android.

Nesse caso, basta acessar o método onReceive do BroadcastReceiver e adicionar a seguinte linha:

new SingularInstallReceiver().onReceive(context, intent);

Por exemplo, se o receptor existente se chamar MyCustomInstallReceiver, ele deverá ter a seguinte aparência:

public class MyCustomInstallReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        // Passar as informações do referenciador de instalação para a Singular
        new SingularInstallReceiver().onReceive(context, intent);
        // ...
    }
}

Se não houver outro receptor de referência de instalação:

Se você não tiver nenhum receptor de referência de instalação em seu aplicativo, poderá permitir que o Singular SDK registre o único receptor simplesmente adicionando o seguinte à sua tag <application> em seu arquivo de manifesto:

<receiver android:exported="true" android:name="com.singular.sdk.SingularInstallReceiver">
    <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER" />
    </intent-filter>
</receiver>

4.5. Gerenciamento de sessões

Para Android API 14 (Ice Cream Sandwich) e superior, o Singular SDK pode gerenciar automaticamente o gerenciamento de sessões. Se a minSdkVersion do seu aplicativo for 14 ou superior, não será necessária nenhuma configuração adicional para o gerenciamento de sessões.

Modificação do tempo limite da sessão

Por padrão, se o aplicativo for executado em segundo plano por 60 segundos ou mais antes de retornar ao primeiro plano, o SDK registrará uma nova sessão.

Para alterar o valor do tempo limite, use withSessionTimeoutInSec(<timeout in seconds>)em SingularConfig antes de inicializar o SDK.

Por exemplo:

// Defina o tempo limite da sessão para 120 segundos
SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET")
.withSessionTimeoutInSec(120); 

Gerenciamento manual de sessões

Se a minSdkVersion do seu aplicativo for inferior a 14, você precisará gerenciar as sessões manualmente chamando os dois métodos de tratamento de sessão do SDK do Singular, onActivityPaused e onActivityResumed, de cada uma de suas atividades.

Observação: se você tiver uma classe de atividade base comum personalizada da qual todas as outras atividades são derivadas, poderá colocar essas chamadas para onActivityResumed e onActivityPaused nos métodos "onResume e onPause" da atividade comum.

@Override
protected void onResume() {
    super.onResume();
    Singular.onActivityResumed();
    .... // outro código, se houver
}

@Override
protected void onPause() {
    super.onPause();
    Singular.onActivityPaused();
    .... // outro código, se houver
}

4.6. Uso da interface JavaScript

O Singular fornece uma interface JavaScript que você pode usar para chamar o Singular a partir do código javaScript em seu aplicativo.

Por exemplo, se você configurar a interface JavaScript, poderá enviar eventos para o Singular a partir do código JavaScript da seguinte forma:

Exemplo de evento

SingularInterface.event('event');
SingularInterface.event('test',
    JSON.stringify({"a1":"bar", "a2":"boo", "a3":"baz"}));

A interface é compatível com os seguintes métodos do SDK:

• setCustomUserID
• unsetCustomUserID
• event
• revenue

Para ativar a interface JavaScript, adicione as seguintes linhas de código à sua atividade principal, em que "myWebView" é o nome da sua visualização da Web.

SingularJSInterface singularJSInterfaceInstance = new SingularJSInterface(this);
singularJSInterfaceInstance.setWebViewId(R.id.webview);
myWebView.addjavascriptInterface(singularJSInterfaceInstance, "SingularInterface");

Seu método onCreate pode ter a seguinte aparência:

public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    WebView myWebView = (WebView) this.findViewById(R.id.webview);
    WebSettings webSettings = myWebView.getSettings();
    webSettings.setjavaScriptEnabled(true);
    myWebView.loadUrl("file:///android_asset/index.html");

    SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");
    Singular.init(this, config);
    SingularJSInterface singularJSInterfaceInstance = 
        new SingularJSInterface(this);
    singularJSInterfaceInstance.setWebViewId(R.id.webview);
    myWebView.addjavascriptInterface(singularJSInterfaceInstance,
        "SingularInterface");
}

4.7. Coleta do OAID (Open Advertising ID)

Nos países que não usam o Google Play, os dispositivos Android não têm um Google Advertising ID (GAID, também chamado de AIFA no Singular). Em vez disso, os dispositivos podem oferecer um identificador chamado OAID (Open Advertising Identifier) que pode ser usado para rastrear sessões e eventos provenientes do dispositivo.

O OAID é oferecido atualmente em dispositivos da Huawei e de marcas que pertencem à Mobile Security Alliance (MSA).

Para que seu aplicativo colete o OAID, primeiro é necessário integrar o SDK da MSA e o SDK do OAID da Huawei. É necessário integrar os dois SDKs para poder coletar o OAID em todas as plataformas que o oferecem.

Em seguida, para informar ao SDK da Singular que deve usar o OAID para rastreamento, adicione uma chamada para withOAIDCollection no objeto de configuração antes de inicializar a Singular.

SingularConfig config = new SingularConfig("SDK KEY","SDK SECRET")
    .withOAIDCollection();
Singular.init(context, config);

O SDK do Singular detectará automaticamente se o dispositivo tem um OAID e qual SDK de OAID deve ser usado para coletar o identificador.

4.8. Coleta do número IMEI

Se o seu aplicativo for oferecido em países que não usam o Google Play, os dispositivos não terão um ID de publicidade do Google.Nesse caso, talvez você queira coletar o IMEI (International Mobile Equipment Identity) do dispositivo.

Observação: Se você usa o Google Play Services, não deve coletar o número IMEI, pois isso é uma violação do contrato de serviço do Google Play.

Para coletar o número IMEI:

Adicione a permissão android.permission.READ_PHONE_STATE ao arquivo AndroidManifest.xml do aplicativo:

<uses-permission android:name="android.permission.READ_PHONE_STATE"/>

Adicione um código como o seguinte para obter o número IMEI do dispositivo:

TelephonyManager telephonyManager = (TelephonyManager)getSystemService(Context.TELEPHONY_SERVICE);

String imei = null;

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    imei = telephonyManager.getImei();
} else {
    imei = telephonyManager.getDeviceId();
}

Para enviar o número IMEI para a Singular, use um dos métodos a seguir:

Recomendado: Defina o número IMEI em SingularConfig usando withIMEI antes de inicializar o SDK da Singular, como no exemplo a seguir. Isso torna o número IMEI disponível para a Singular desde a primeira sessão.

SingularConfig config = new SingularConfig("SDK KEY","SDK SECRET")
  .withIMEI("537769845792516");
Singular.init(context, config);

Para definir o número IMEI em qualquer ponto do código após a inicialização do SDK, chame setIMEI.

Singular.setIMEI(IMEIString);

4.9. 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.

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

Singular.trackingOptIn();

Singular.stopAllTracking();

Singular.resumeAllTracking();

Singular.isAllTrackingStopped();