O SDK da Singular está disponível como um plug-in para o Segment, chamado de Destino" Device-Mode". As instruções abaixo ilustram como adicionar o Singular Destination no Segment.
Guia para | Equipes de engenharia |
Pré-requisitos | Este artigo pressupõe que você já tenha o SDK do Segment Analytics para iOS ou Android integrado ao seu aplicativo. |
Para usar essa integração, você deve estar usando o SDK do Segment Mobile Analytics para: iOS (Obj-C nativo ou Swift), Android (Java ou Kotlin). Essa integração NÃO é compatível com nenhuma outra estrutura, incluindo Unity, Factual Engine, React Native ou Xamarin, etc.!
- Atribuição de instalação básica
- Suporte à SkAdNetwork 3 (SKAN 3.0)
- Atribuição de anúncios de pesquisa da Apple
- Rastreamento de eventos personalizados no aplicativo
- Rastreamento de receita
- ID de usuário personalizado
- Suporte à SkAdNetwork 4 (SKAN 4.0)
- Atribuição de referenciador da instalação META
- Links profundos
- Suporte limitado ao compartilhamento de dados
Se você precisar de suporte para outras estruturas ou desejar a "funcionalidade completa de recursos" oferecida pelo SDK da Singular, deverá implementar o SDK da Singular independentemente da Segment. Veja as opções de SDK e estruturas AQUI.
Primeiros passos
- No aplicativo da Web do Segment, clique em "Catalog" (Catálogo) no menu "Connections" (Conexões).
- Procure por "Singular" no Catálogo, selecione-o e clique no botão "Add Destination" (Adicionar destino).
- Selecione as origens às quais conectar o destino e clique em "Next" (Avançar).
- Nomeie o destino e clique em "Create destination" (Criar destino)
- Obtenha sua "SDK KEY" do Singular, encontrada no Singular Dashboard em "Developer Tools > SDK Integration > SDK Keys", e adicione-a às "Connection Settings" do segmento, em "API Key" e "Secret".
Importante: certifique-se de usar a Singular SDK Key para o valor da API Key no Segment. Se a chave errada for usada, a Singular não receberá nenhum dado.
Configuração adicional
Para usar os recursos somente nativos dessa integração, você precisará incluir a biblioteca Singular adicionando essas linhas à sua configuração de dependência:
- Adicione AdServices.framework em Link Binary With Libraries e marque-o como Optional (disponível somente para dispositivos com iOS 14.3 e superior). Isso é necessário para oferecer suporte à atribuição do Apple Search Ads.
- Adicione o pod de integração do Singular Segment ao podfile do seu aplicativo da seguinte forma:
pod 'Segment-Singular'
- Importe a biblioteca Singular em seu arquivo:
#import <Segment-Singular/SEGSingularIntegrationFactory.h>
- Por fim, registre o Singular com o SDK do Segment
SEGAnalyticsConfiguration *configuration = [SEGAnalyticsConfiguration configurationWithWriteKey:@”<SEGMENT_WRITE_KEY>”]; // Enable this to record certain application events automatically!
configuration.trackApplicationLifecycleEvents = YES;
// Enable this to record screen views automatically!
configuration.recordScreenViews = YES;
// Add any of your Device-mode destinations.
configuration use:[SingularIntegrationFactory instance]];
[SEGAnalytics setupWithConfiguration:configuration];let configuration = AnalyticsConfiguration(writeKey: "<SEGMENT_WRITE_KEY>")
// Enable this to record certain application events automatically!
configuration.trackApplicationLifecycleEvents = true
// Enable this to record screen views automatically!
configuration.recordScreenViews = true
// Add any of your Device-mode destinations. configuration.use(SingularIntegrationFactory.instance())
Analytics.setup(with: configuration) - [ OPCIONAL] Implementar suporte ao SKAN
O SDK da Singular pode controlar sua integração com a SKAdnetwork. Para obter detalhes sobre como isso funciona, consulte SDK do iOS: Adição de suporte a SKAdNetwork.
Para permitir que a Singular controle sua integração com a SKAdNetwork, adicione o seguinte código antes da inicialização do SDK do Segment:
[SingularIntegation setSKANOptions:YES isManualSkanConversionManagementMode: NO withWaitForTrackingAuthorizationWithTimeoutInterval:@0 withConversionValueUpdatedHandler:^(NSInteger conversionValue) { NSLog(@"Your SKAN handler %ld",conversionValue); }];
SingularIntegation.setSKANOptions(
true,
isManualSkanConversionManagementMode: false,
withWaitForTrackingAuthorizationWithTimeoutInterval: NSNumber(value: 0), withConversionValueUpdatedHandler: { conversionValue in print(String(format: "Your SKAN handler %ld", conversionValue)) })
Análise do Segment para Android
- Adicione a dependência de integração do Singular Segment ao arquivo build.gradle do seu aplicativo:
compile 'net.singular.segment.integration:singular_segment_sdk:+'
- Adicione as permissões necessárias ao arquivo AndroidManifest.xml. Inclua as seguintes permissões:
<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" />
- Depois de adicionar a dependência, você deve importar a integração
import net.singular.segment.integration.SingularIntegration;
- Por fim, adicione o código para inicializar o SDK da Singular
Adicione .trackApplicationLifecycleEvents() para enviar eventos de abertura de aplicativo, atualização de aplicativo e instalação de aplicativo para o Singular.
static final String SEGMENT_WRITE_KEY = "<YOUR_KEY>"; @Override protected void onCreate(Bundle savedInstanceState) {
Analytics analytics = new Analytics.Builder(this , SEGMENT_WRITE_KEY) .use(SingularIntegration.FACTORY .logLevel(Analytics.LogLevel.VERBOSE) .recordScreenViews() .trackApplicationLifecycleEvents() .build(); Analytics.setSingletonInstance(analytics); }
Instalar atribuição
Habilite o rastreamento automático de eventos de ciclo de vida (Application Opened, Application Installed, Application Updated) usando parâmetros de configuração de inicialização(iOS, Android) para rastrear instalações e sessões no Singular. A "sessão" do Singular será enviada automaticamente pela integração, desde que você inclua os eventos acima.
Rastreamento de evento personalizado
Se você não estiver familiarizado com as especificações do Segment, dê uma olhada para entender o que o método Track faz.
Use a função de rastreamento do Segment para que os eventos sejam traduzidos e enviados para a Singular:
[[SEGAnalytics sharedAnalytics] track:@"simple event"];
Analytics.with(this).track("event_name");
O Segment inclui todas as propriedades do evento como parâmetros de retorno de chamada no evento do Singular.
Os eventos estarão disponíveis em relatórios e exportações no nível do usuário.
Rastreamento de receita
A Singular receberá o rastreamento de receita quando um evento contendo a propriedade revenue for enviado (incluindo o valor zero). Opcionalmente, você pode passar a moeda (como um código de moeda ISO 4217 ). A moeda padrão é USD.
[[SEGAnalytics sharedAnalytics] track:@"segment revenue event" properties:@{@"currency": @"USD", @"revenue":@20}];
Analytics.with(this).track("purchase", new Properties().putRevenue(2.5).putValue("currency","USD"));
Observação: passe a moeda como um código de moeda ISO 4217 de três letras, por exemplo, "USD", "EUR", "INR".
ID de usuário personalizado
Você pode enviar seu ID de usuário do segmento para a Singular usando o método Segment identify.
Observação: se você usar a solução Cross-Device da Singular, deverá coletar o mesmo UserID em todas as plataformas.
- O ID do usuário pode ser qualquer identificador e não deve expor PII (informações de identificação pessoal). Por exemplo, você não deve usar o endereço de e-mail, o nome de usuário ou o 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 outras partes.
- O valor do ID de usuário, quando definido, persistirá até que seja redefinido usando o método de redefinição de segmento ou até que o aplicativo seja desinstalado. Fechar ou reiniciar o aplicativo não desativa a ID do usuário.
Siga as etapas aqui para configurar para: iOS, Android.
[[SEGAnalytics sharedAnalytics] identify:@"segment custom user id"];
Analytics.with(context).identify("myUserId");
Para cancelar a definição do ID de usuário personalizado, chame o método de redefinição.
[[SEGAnalytics sharedAnalytics] reset];