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 Adicionando o 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 = uri("https://maven.singular.net/") }
        }
   }

   OU em versões mais antigas do Gradle, Adicione o repositório 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 'com.singular.sdk:singular_sdk:12.7.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 tiver desativado as dependências transitivas para o SDK Singular, adicione o seguinte à sua 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.7.0</version>
</dependency>

-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
# Uncomment this line in case your are calling the 'revenue' function using the Google billing library
#-keep public class com.android.billingclient.** { *; }

1.3. Adicionando as permissões necessárias

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

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

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 e tiver como alvo o Android 11 ou superior:

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

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

2.1. Importando a biblioteca Singular

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

import com.singular.sdk.*;

import com.singular.sdk.*

2.2. Construindo um objeto de configuração

Antes de inicializar o SDK, é preciso criar um objeto SingularConfig. Este objeto conterá o seguinte:

1. Sua SDK Key e SDK Secret (para obtê-los, entre na sua conta Singular e vá para DEVELOPER TOOLS > SDK Integration > SDK Keys).
2. Opcionalmente, quaisquer preferências de SDK que 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 ID do aplicativo do Facebook no objeto de configuração Singular.
      

      // To enable META Install Referrer
      
      config.withFacebookAppId("INSERT YOUR FACEBOOK APP ID HERE");

   Onde posso encontrar a ID de aplicativo do Facebook 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 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) {
    ...
    // Create a configuration object

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

    // Set up a deep links handler

    config.withSingularLink(
        getIntent(), 
        new SingularLinkHandler() {
            @Override
            public void onResolved(SingularLinkParams params) {
                String deeplink = params.getDeeplink();
                String passthrough = params.getPassthrough();
                boolean isDeferred = params.isDeferred();

                // Add deep link handling code here

            }
        }
    );

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

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

    // Create a configuration object

    val config = SingularConfig("SDK KEY", "SDK SECRET")

    // Set up a deep links handler

    config.withSingularLink(
        intent
    ) { params ->
        val deeplink = params.deeplink
        val passthrough = params.passthrough
        val isDeferred = params.isDeferred

        // Add deep link handling code here

    }

    Singular.init(this, config)
    ...
}

2.3. Adicionando suporte a Deep Linking

Os links profundos são URLs que direcionam os usuários para um conteúdo específico dentro de um aplicativo. Quando um utilizador toca numa hiperligação profunda num dispositivo onde a aplicação já está instalada, a aplicação abre-se diretamente para a página do produto ou experiência pretendida. Os links de rastreamento singulares suportam links diretos e links diretos adiados. Para obter mais detalhes, consulte nossas Perguntas frequentes sobre links diretos e Perguntas frequentes sobre links singulares.

Requisitos

1. Para habilitar links diretos para seu aplicativo, certifique-se de concluir os Pré-requisitos do Singular Links.

2. Implementar o manipulador de links singulares

   O Singular Link Handler fornece um mecanismo de callback para recuperar parâmetros de deep link (_dl), deferred deep link (_ddl) e passthrough (_p) de um link de rastreamento Singular. Esses parâmetros são passados quando o aplicativo é aberto (se já estiver instalado) ou depois que o aplicativo é instalado.

   ---

   Atualizar o objeto de configuração Singular

   Adicione o retorno de chamada SingularLinkHandler ao objeto SingularConfig durante a inicialização do SDK para manipular os dados de entrada do deep link e do deep link adiado.

   Os logs são adicionados em linha para fins de teste.

   JavaKotlin

   // Call SingularLinkHandler
   
   config.withSingularLink(getIntent(), new SingularLinkHandler() {
           @Override
           public void onResolved(SingularLinkParams params) {
               Log.d("Singular", "SingularLinkHandler");
               String deeplink = params.getDeeplink();
               String passthrough = params.getPassthrough();
               boolean isDeferred = params.isDeferred();
   
               // Add deep link handling code here
   
               Log.d("SingularLink", "Deeplink: " + deeplink);
               Log.d("SingularLink", "Passthrough: " + passthrough);
               Log.d("SingularLink", "Is Deferred: " + isDeferred);
           }
       }
   );

   // Call SingularLinkHandler
   
   config.withSingularLink(intent) { singularLinkParams ->
      Log.d("Singular", "SingularLinkHandler")
      val deeplink = singularLinkParams.deeplink
      val passthrough = singularLinkParams.passthrough
      val isDeferred = singularLinkParams.isDeferred
   
      // Add deep link handling code here
   
      Log.d("Singular", "Deeplink: $deeplink")
      Log.d("Singular", "Passthrough: $passthrough")
      Log.d("Singular", "isDeferred: $isDeferred")
   }

   Observação: O SingularLinkHandler é acionado somente quando o aplicativo é aberto por meio de um Singular Link. Para obter mais informações, consulte (consulte as Perguntas frequentes sobre links singulares).

   Notas sobre o comportamento do SingularLinkHandler:

   #

   Notas sobre o comportamento do SingularLinkHandler:

   • Em uma nova instalação, não há uma URL aberta quando o aplicativo é iniciado. Portanto, o Singular deve concluir a atribuição até o último toque (clique) e determinar se o link de rastreamento contém um valor de Deep Link ou Deferred Deep Link (DDL). Esse processo ocorre quando o SDK da Singular envia a primeira sessão para os servidores da Singular. Se aplicável, o valor do deep link é retornado para o SingularLinkHandler do SDK no parâmetro deeplink.

     Para testar esse cenário:

     1. Desinstale o aplicativo do dispositivo (se estiver instalado).
     2. Reponha o seu Google Advertising ID (GAID).
     3. Clique no link de rastreamento Singular com DDL configurado a partir do dispositivo.
     4. Instale e abra o aplicativo.

     A atribuição deve ser concluída com êxito e o valor DDL será passado para o aplicativo.

   • Se um parâmetro passthrough (_p) for incluído no link de rastreamento, o parâmetro passthrough do SingularLinkHandler conterá os dados correspondentes. Isto é útil para capturar dados adicionais do clique na aplicação.
   • Se o aplicativo já estiver instalado, clicar em um Singular Link abrirá o aplicativo. A Singular usa a tecnologia Android App Links para fazer isso. O sistema operacional Android fornecerá uma URL aberta contendo todo o link de rastreamento do Singular. Durante a inicialização do SDK, o Singular SDK analisará o Android Intent, extrairá os valores de deeplink e passthrough e os retornará através do SingularLinkHandler.

Opções avançadas

config.withDDLTimeoutInSec(30);

.withDDLTimeoutInSec(30)

2.4. Inicializando o Singular

O SDK do Singular deve ser inicializado toda vez que seu aplicativo for aberto. Esse é 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).

Para inicializar o Singular, use o seguinte código:

Singular.init(context, config);

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 método onCreate da atividade principal, bem como em qualquer atividade que será aberta diretamente por meio de um deep link.

2.5. Enviando o ID de usuário para o Singular (opcional)

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

• 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");

2.6. Implementando propriedades globais (opcional)

O Singular SDK permite definir propriedades personalizadas adicionais para enviar aos servidores 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 status do aplicativo ou qualquer outra coisa. Depois de definir essas propriedades, elas ficam disponíveis como dimensões nos seus relatórios e você pode usá-las para dividir seus dados.

Por exemplo, se tiver uma aplicação de jogos, pode definir uma propriedade chamada "Nível" e defini-la inicialmente como "0". Qualquer sessão e evento enviado da aplicação será enviado com "Nível": "0". Quando o utilizador subir de nível, a propriedade é reposta a "1" e assim sucessivamente. Pode então obter os seus relatórios, incluindo sessões, contagens de eventos e dados de receitas, repartidos por nível de utilizador.

• Pode definir até 5 propriedades globais.
• Estas propriedades persistem entre execuções da aplicação (com o valor mais recente que lhes atribuiu) até que as desfaça ou o utilizador desinstale a aplicação.
• Cada nome e valor de propriedade pode ter até 200 caracteres. Se passar um nome ou valor de propriedade mais longo, este será truncado para 200 caracteres.
• As propriedades globais estão acessíveis e disponíveis em exportações e postbacks ao nível do utilizador. 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!

Definindo propriedades globais através do SingularConfig

É possível usar o método withGlobalProperty para definir propriedades globais através 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.

// Set two global properties and override any existing values

SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET")
  .withGlobalProperty(“MyProperty”, “MyValue”, true)
  .withGlobalProperty(“AnotherProperty”, “AnotherValue”, true);

Definir propriedades globais após a inicialização

Utilize os seguintes métodos para definir, anular e recuperar propriedades globais em qualquer altura da execução da aplicação.

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

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

Singular.unsetGlobalProperty(“MyProperty”);

Singular.clearGlobalProperties();

3. Acompanhamento de eventos e receitas

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, 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 que são eventos e atributos padrão?

O Singular suporta uma variedade de eventos padrão. Estes eventos normalmente utilizados são muitas vezes 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 de eventos sem que você tenha que 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.

Envio de eventos

Em seu código, envie eventos para a Singular usando os métodos eventJSON ou event (recomendamos 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 para o Android SDK, por exemplo, sngTutorialComplete. Veja os exemplos de código abaixo.
• Se enviar quaisquer eventos personalizados (eventos que a sua organização pretende medir e que não correspondem a nenhum dos eventos padrão do Singular), utilize qualquer cadeia de caracteres que esteja em conformidade com as limitações.

// Example 1:

// Send the standard event sng_tutorial_complete with the

// recommended standard attributes


JSONObject att = new JSONObject();
try {
    att.put(Attributes.sngAttrContent.toString(), "Telugu");
    att.put(Attributes.sngAttrContentId.toString(), 32);
    att.put(Attributes.sngAttrContentType.toString(), "video");
    att.put(Attributes.sngAttrSuccess.toString(), 92);
} catch (JSONException e) {
    e.printStackTrace(); // Or log the exception


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

// Example 2:

// Send a custom event named "bonus_points_earned" with custom attributes

JSONObject att = new JSONObject();
try {
    att.put("Points", 500);
    att.put("score", 650);
} catch (JSONException e) {
    e.printStackTrace(); // Or log the exception


}
Singular.eventJSON("Bonus Points Earned", att);

// Example 1:

// Send the standard event sng_tutorial_complete with the

// recommended standard attributes


val att = JSONObject().apply {
    put(Attributes.sngAttrContent.toString(), "Telugu")
    put(Attributes.sngAttrContentId.toString(), 32)
    put(Attributes.sngAttrContentType.toString(), "video")
    put(Attributes.sngAttrSuccess.toString(), 75)
}
Singular.eventJSON(Events.sngTutorialComplete.toString(), att)

// Example 2:

// Send a custom event named "bonus_points_earned" with custom attributes

val att = JSONObject().apply {
    put("Points", 500)
    put("score",650)
}
Singular.eventJSON("Bonus Points Earned", att)

// Example 1:

// Send the standard event "Subscribe" (sng_subscribe) without any attributes

Singular.event(Events.sngSubscribe.toString());

// Example 2:

// Send the standard event "sng_tutorial_complete" with the 

//recommended standard attributes
Singular.event(Events.sngTutorialComplete.toString(),
    Attributes.sngAttrContent.toString(), "Spanish",
    Attributes.sngAttrContentId.toString(), 52,
    Attributes.sngAttrContentType.toString(), "video",
    Attributes.sngAttrSuccess.toString(), 46
);

// Example 3:

// Send a custom event named "SignUp" without any custom attributes

Singular.event("SignUp");

// Example 4:

// Send a custom event named "bonus_points_earned" with a custom attribute

Singular.event("Bonus Points Earned", "Points", 500);

// Example 1:

// Send the standard event "Subscribe" (sng_subscribe) with no attributes

Singular.event(Events.sngSubscribe.toString())

// Example 2:

// Send the standard event sng_tutorial_complete with the

// recommended standard attributes

Singular.event(Events.sngTutorialComplete.toString(),
    Attributes.sngAttrContent.toString(), "Telugu",
    Attributes.sngAttrContentId.toString(), "32",
    Attributes.sngAttrContentType.toString(), "video",
    Attributes.sngAttrSuccess.toString(), "yes"
)

// Example 3:

// Send a custom event named "SignUp" with no custom attributes

Singular.event("SignUp")

// Example 4:

// Send a custom event named "bonus_points_earned" with a custom attribute

Singular.event("Bonus Points Earned", "Points", 500)

3.2. Rastreamento de receita

A Singular captura eventos de receita de compras no aplicativo (IAP), assinaturas e receita personalizada para medir o desempenho da campanha e o retorno sobre o gasto com anúncios (ROAS). Os dados de receita ficam disponíveis por meio de três canais principais:

• Relatórios interactivos no dashboard Singular
• Registos de exportação detalhados e destinos de dados ETL para análise personalizada
• Postbacks em tempo real para plataformas externas

Este acompanhamento abrangente das receitas permite tomar decisões baseadas em dados sobre os gastos de marketing e a otimização das campanhas, proporcionando flexibilidade na forma como os dados são consumidos e analisados.

Requisitos

Melhores práticas

Implementações de rastreamento de receita

Singular.revenue(String currency, double amount, Object purchase)

Singular.revenue("USD", 5.50, purchase);

Singular.revenue("USD", 5.50, purchase)

Singular.customRevenue(String eventName, String currency, double amount, Object purchase)

Singular.customRevenue("MyCustomRevenue", "USD", 5.50, purchase);

Singular.customRevenue("MyCustomRevenue", "USD", 5.50, purchase)

Singular.revenue(String currency, double amount)

Singular.revenue(String currency, double amount, String productSKU, String productName, String productCategory, int productQuantity, double productPrice)

Singular.revenue(String currency, double amount, Map<String, Object> attributes)

Singular.revenue("USD", 5.50);

Singular.revenue("EUR", 5.00, "SKU1928375", "Reservation Fee", "Fee" , 1, 5.00);

Map<string, object="Object"> attributes = new HashMap<>();
attributes.put("product_id", "com.app.premium");
attributes.put("transaction_id", "T12345");
attributes.put("quantity", 1);
attributes.put("is_trial", false);

// Call the revenue method

Singular.revenue("USD", 9.99, attributes);

Singular.revenue("USD", 5.50)

Singular.revenue("EUR", 5.00, "SKU1928375", "Reservation Fee", "Fee" , 1, 5.00)

val attributes = mutableMapOf<String, Any>().apply {
    put("product_id", "com.app.premium")
    put("transaction_id", "T12345")
    put("quantity", 1)
    put("is_trial", false)
}

// Call the revenue method

Singular.revenue("USD", 9.99, attributes)

Singular.customRevenue(String eventName, String currency, double amount)

Singular.customRevenue(String eventName, String currency, double amount, String productSKU, String productName, String productCategory, int productQuantity, double productPrice)

Singular.customRevenue(String eventName, String currency, double amount, Map<String, Object> attributes)

Singular.customRevenue("MyCustomRevenue", "USD", 5.50);

Singular.customRevenue("MyCustomRevenue", "EUR", 5.00, "SKU1928375", "Reservation Fee", "Fee" , 1, 5.00);

Map<string, object="Object"> attributes = new HashMap<>();
attributes.put("product_id", "com.app.premium");
attributes.put("transaction_id", "T12345");
attributes.put("quantity", 1);
attributes.put("is_trial", false);

// Call the revenue method

Singular.customRevenue("MyCustomRevenue", "USD", 9.99, attributes);

Singular.customRevenue("MyCustomRevenue", "USD", 5.50)

Singular.customRevenue("MyCustomRevenue", "EUR", 5.00, "SKU1928375", "Reservation Fee", "Fee" , 1, 5.00)

val attributes = mutableMapOf<String, Any>().apply {
    put("product_id", "com.app.premium")
    put("transaction_id", "T12345")
    put("quantity", 1)
    put("is_trial", false)
}

// Call the revenue method

Singular.customRevenue("MyCustomRevenue", "USD", 9.99, attributes)
        

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

4. Opções avançadas

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

Nota: Esta funcionalidade está disponível na versão 12.1.1+ do SDK. Uma vez criadas, as ligações curtas permanecem activas durante 30 dias.

Use links curtos para transformar Links Singulares longos e cheios de parâmetros em links mais curtos e mais seguros que são convenientes para compartilhamento.

Normalmente, pretende criar ligações curtas de forma dinâmica para que os utilizadores da sua aplicação possam partilhá-las com amigos para os convidar a utilizar a aplicação.

Para criar um link curto, você precisa de:

• Um link singular que leva ao download do seu aplicativo (consulte as Perguntas frequentes sobre links singulares).
• Quaisquer parâmetros que queira adicionar ao link dinamicamente (consulte Parâmetros de link de rastreamento para obter a lista de opções).
• O nome e a 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.

// Create a JSON object to add parameters to the Singular Link (if they don't exist in the link URL yet)

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", // The original Singular Link URL

  "Referrer Name",
  "Referrer ID",
  params,
  new ShortLinkHandler() { 
    @Override
      public void onSuccess(final String shortLinkURL) {
        view.post(new Runnable() {
          @Override
          public void run() {
            // Add your share logic here

          }   
        });
      }

    @Override
    public void onError(final String error) {  
      view.post(new Runnable() {    
        @Override
        public void run() { 
          // Logic to retry/abort/modify the params passed to 

          // the function, based on the cause of the error

        }
      });
    }
});

// Create a JSON object to add parameters to the Singular Link (if they don't exist in the link URL yet)

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",  // The original Singular Link URL

    "Referrer Name",
    "Referrer ID",
    params,
    object : ShortLinkHandler {
        override fun onSuccess(shortLinkURL: String) {
            view.post(Runnable {
                // Add your share logic here

            })
        }

        override fun onError(error: String) {
            view.post(Runnable {
                // Logic to retry/abort/modify the params passed to

                // the function, based on the cause of the error

            })
        }
    })

Adicionar suporte a_Ad_Revenue_Attribution_Support

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

4.3. Rastreio 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 a utilizar o FCM, siga as instruções da Google sobre como configurar uma aplicação cliente Firebase Cloud Messaging no Android.

Requisitos do FCM ( fonte )

Os clientes FCM requerem 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. Tenha em atenção que não está limitado a implementar as suas aplicações Android através da Google Play Store.

Os utilizadores/dispositivos que não estejam a executar versões suportadas do Android não estarão disponíveis para o rastreio de desinstalação Singular.

II. Atualizar o arquivo AndroidManifest.xml:

Actualize o seu ficheiro AndroidManifest.xml para adicionar o filtro de intenção necessário para a sua aplicação (substitua MyFirebaseMessagingService pela sua classe que implementa o Serviço Firebase):

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

III. Registar e enviar o FCM Device Token:

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

Singular.setFCMDeviceToken(String fcmDeviceToken);

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

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

O install referrer é a ferramenta mais precisa da Singular para determinar a atribuição, além de ajudar a Singular a detetar 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 recetor 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 aceder ao método onReceive do BroadcastReceiver e adicionar a seguinte linha:

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

Por exemplo, se o recetor existente se chama MyCustomInstallReceiver, deve ter o seguinte aspeto:

public class MyCustomInstallReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        // Pass install referrer information on to Singular

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

    }
}

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

Se você não tiver nenhum recetor de referência de instalação em seu aplicativo, poderá permitir que o Singular SDK registre o único recetor 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. Gerenciando sessões

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

Modificando o 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:

// Set the session timeout to 120 seconds

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

Gerenciamento manual de sessão

Se a minSdkVersion do seu aplicativo for inferior a 14, você precisará gerenciar 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.

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

@Override
protected void onResume() {
    super.onResume();
    Singular.onActivityResumed();
    .... //other code if any
}

@Override
protected void onPause() {
    super.onPause();
    Singular.onActivityPaused();
    .... //other code if any
}

4.6. Usando a interface JavaScript

O Singular fornece uma interface JavaScript que pode ser usada para chamar o Singular de dentro 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 suporta os seguintes métodos do SDK:

• setCustomUserID
• unsetCustomUserID
• evento
• receita

Para ativar a interface JavaScript, adicione as seguintes linhas de código à sua atividade principal, em que "myWebView" é o nome da sua visualização 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. Recolher o OAID (Open Advertising ID)

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

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

Para que a sua aplicação possa recolher o OAID, primeiro tem de integrar o SDK da MSA e o SDK do OAID da Huawei. É necessário integrar ambos os SDKs para poder recolher o OAID em todas as plataformas que o oferecem.

Em seguida, para dizer ao SDK Singular para usar o OAID para rastreamento, adicione uma chamada para withOAIDCollection no objeto de configuração antes de inicializar o 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. Coletando o número IMEI

Se a sua aplicação for oferecida em países que não utilizam o Google Play, os dispositivos não têm um ID de publicidade do Google. Neste caso, pode querer recolher o IMEI (International Mobile Equipment Identity) do dispositivo.

Nota: Se utilizar o Google Play Services, não deve recolher o número IMEI porque é uma violação do contrato de serviço do Google Play.

Para recolher o número IMEI:

Adicione a permissão android.permission.READ_PHONE_STATE ao ficheiro AndroidManifest.xml da aplicação:

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

Adicione 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 o Singular, use um dos seguintes métodos:

Recomendado: Defina o número IMEI em SingularConfig usando withIMEI antes de inicializar o SDK do Singular, como no exemplo a seguir. Isso torna o número IMEI disponível para o 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 a funcionalidade de proteção da privacidade para o ajudar a cooperar com quaisquer parceiros que possam estar em conformidade com as leis de privacidade do consumidor, como o GDPR e o CCPA(California Consumer Privacy Act). 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();