Guia de integração iOS SDK

 

Problemas durante a integração? Consulte as perguntas frequentes abaixo.

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. Instalação do SDK

Você pode instalar o SDK da Singular usando o CocoaPods, o Swift Package Manager ou uma biblioteca estática.

Instalando o SDK usando o CocoaPods
  1. Faça download e instale a versão mais recente do CocoaPods.
  2. Para criar um podfile, navegue até a pasta raiz do projeto no Terminal e digite:

    pod init
  3. Para adicionar a dependência do Singular SDK, adicione o seguinte ao Podfile do seu projeto:

    pod 'Singular-SDK'

    Por exemplo:

    pod_for_swiftcocoapods.png

  4. Em seu Terminal, navegue até a pasta raiz do projeto e execute:

    pod install
  5. Desse ponto em diante, abra o arquivo de espaço de trabalho do Xcode .xcworkspace para abrir o projeto, em vez do arquivo .xcodeproj.
  6. Crie um cabeçalho de ponte Swift de acordo com as instruções abaixo.
Instalação do SDK usando o gerenciador de pacotes Swift
  1. No Xcode, vá para File > Add Packages e insira o repositório Singular SDK GitHub:

    https://github.com/singular-labs/Singular-iOS-SDK

    update_sdk_version_1.png

  2. Atualize a versão do Singular SDK:

    update_sdk_version_2.png

  3. Clique no botão Add Package (Adicionar pacote ).
  4. Vá para Build Phases > Link Binary with Libraries e adicione a biblioteca AdServices.framework. Certifique-se de marcá-la como Optional (opcional), pois ela só está disponível para dispositivos com iOS 14.3 ou superior.

    link_binary_adservices.png

  5. Vá para Build Settings > Linking > Other Linker Flags e atualize Other Linker Flags com os seguintes itens:

    frameworks.png

    other_linker_flags.png

  6. Crie um cabeçalho de ponte Swift de acordo com as instruções abaixo.
Instalação da estrutura do Singular SDK (biblioteca estática)

O download e a instalação da estrutura Singular só são necessários se você NÃO estiver usando o método CocoaPods ou SPM acima.

Está fazendo upgrade do Singular SDK 12.3.2 ou inferior?

Siga as etapas abaixo para remover a biblioteca estática antiga

  1. Navegue até os arquivos do projeto e remova a biblioteca estática Singular. Normalmente, você deve ter uma pasta com o nome Singular-iOS-sdk-v12.3.2. Clique com o botão direito do mouse na pasta e exclua-a do projeto.
  2. Prossiga para a próxima seção para instalar a nova estrutura

Adição da estrutura Singular pela primeira vez

  1. Faça download e descompacte a estrutura do SDK.

    Selecione a estrutura correta para sua implementação:

    • Para o Xcode 12 e superior, use o .xcframework [BAIXE AQUI]
    • Para o Xcode 11 e versões anteriores, use o endereço .framework [BAIXE AQUI]
  2. Adicione a pasta descompactada a uma pasta em seu projeto do Xcode:

    No Xcode, clique com o botão direito do mouse em Your App Name > Add Files To [Your Project Name] Na caixa de diálogo que se abre, selecione Options > Create Groups e adicione a pasta onde você descompactou o SDK.





    A estrutura do Singular deve estar agora em seu projeto

  3. Para adicionar as bibliotecas necessárias:

    • No Xcode, selecione Build Phases > Link Binary With Libraries.
    • Clique em + e adicione as seguintes bibliotecas:

      Libsqlite3.0.tbd
      SystemConfiguration.framework
      Security.framework
      Libz.tbd
      AdSupport.framework
      WebKit.framework
      StoreKit.framework
      AdServices.framework (marcar como Opcional, pois só está
      disponível para dispositivos com iOS 14.3 e superior).
  4. Incorporar e assinar a estrutura Singular
    • Navegue até General > Frameworks, Libraries, and Embedded Content (Geral > Estruturas, bibliotecas e conteúdo incorporado)
    • Ajustar a estrutura Singular para ser "Embed & Sign"

Adição do cabeçalho de ponte Swift

Se você instalou o SDK usando o CocoaPods ou o Swift Package Manager, deverá criar um Bridging Header para que o Swift use as bibliotecas Obj-C do Singular SDK.

  1. Em seu projeto, crie um novo arquivo do tipo Header e nomeie-o YourProjectName-Bridging-Header.

    new_header_file.png

  2. Abra o arquivo e adicione o seguinte:

    #import <Singular/Singular.h>

    Por exemplo:

    swift_cocoapods_import_singular.png

  3. Vá para Build Settings > Objective-C Bridging Header e adicione o caminho relativo do arquivo:

    objective_c_bridging_header.png

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

Importante:

  • Para usar o Swift, você deve ter um Bridging Header (consulte o guia acima).
  • Se você adicionou o Singular SDK usando o Swift Package Manager, certifique-se de atualizar Build Settings > Other Linker Flags conforme explicado acima.

2.1. Importando a biblioteca Singular

No SceneDelegate, AppDelegate ou em qualquer arquivo em que o Singular será usado, importe a biblioteca de classes do Singular para começar a usar o SDK do Singular.

// Se instalado com o Cocoapods ou o Swift Package Manager
import Singular
          
// Se instalado manualmente em Objective-C (Nova estrutura)
#import <Singular/Singular.h>

// Se instalado manualmente em Objective-C (Legado)
#import "Singular.h"

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

Antes de inicializar a funcionalidade do Singular em seu código, é necessário criar um objeto de configuração do Singular e definir todas as suas opções de configuração. Esse bloco de código deve ser adicionado ao SceneDelegate (ou, se você não estiver usando o SceneDelegate, adicione-o ao AppDelegate).

O exemplo de código a seguir cria um objeto de configuração e define algumas opções de configuração comuns, como ativar a SKAdNetwork no Managed Mode e definir um tempo limite para aguardar uma resposta ATT.

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

Exemplo: Criação de um objeto de configuração com algumas opções comuns

SwiftObjective-C
func getConfig() -> SingularConfig? {
// Crie o objeto de configuração com a chave SDK e o segredo SDK
guard let config = SingularConfig(apiKey: Constants.APIKEY,
andSecret: Constants.SECRET) else { return nil } // Defina um atraso de 300 segundos antes da inicialização
// para aguardar a resposta ATT do usuário.
// Remova isso se não estiver exibindo um prompt ATT! config.waitForTrackingAuthorizationWithTimeoutInterval = 300 // Suporte a domínios ESP personalizados config.espDomains = ["links.your-website-domain.com"] // Definir um método de tratamento para links diretos config.singularLinksHandler = { params in self.handleDeeplink(params: params) } return config }

Observação: a partir da versão 12.0.6 do Singular iOS SDK, a SKAdNetwork é ativada por padrão.

Se você ainda estiver usando uma versão mais antiga do SDK, precisará ativar a SKAdNetwork usando o seguinte código ao criar o objeto de configuração:

SwiftObjective-C
// Ativar SKAdNetwork no modo gerenciado
config.skAdNetworkEnabled = true

2.3. Personalização das opções de SKAdNetwork

SKAdNetwork é a estrutura da Apple para determinar a atribuição de instalações móveis sem comprometer a privacidade do usuário final. A SKAdNetwork permite medir o desempenho das suas campanhas de marketing de aplicativos sem compartilhar as informações de identificação pessoal do usuário.

Por padrão, a SKAdNetwork é ativada no Managed Mode, em que o valor da conversão é gerenciado diretamente pela Singular no lado do servidor. Se estiver usando o Managed Mode, você não precisará adicionar nenhum código ao seu aplicativo para lidar com a SKAdNetwork.

Isso permite o máximo de flexibilidade, pois você pode definir e alterar seus valores de conversão por meio da plataforma Singularsem modificar o código do lado do cliente.

Esse modo gerenciado no lado do servidor também o ajuda a lidar com os temporizadores da SKAdNetwork. A SKAdNetwork permite que você atualize o valor de conversão dentro de 24 horas a partir do momento do registro na SKAdNetwork. Qualquer chamada para atualizar o valor de conversão estende o cronômetro por mais 24 horas. Portanto, ao escolher seus eventos de conversão, você terá que se certificar de que os eventos ocorram dentro dessa janela de atualização. No modo gerenciado, você pode alterar a configuração do evento de conversão a qualquer momento sem lançar uma nova versão do aplicativo.

Uso da SKAdNetwork no modo manual (avançado)

Saiba como usar a SKAdNetwork no modo manual

Se você quiser atualizar o valor de conversão por conta própria usando o código do aplicativo, primeiro terá que definir o sinalizador manualSkanConversionManagement na Singular Config. Isso permite que você use vários métodos do SDK para recuperar e atualizar o valor de conversão manualmente.

Para ativar o modo manual:

SwiftObjective-C
func getConfig() -> SingularConfig? {
// Opções de configuração singulares
guard let config = SingularConfig(apiKey: Constants.APIKEY,
andSecret: Constants.SECRET) else {
return nil
}
... config.manualSkanConversionManagement = true ... return config }

Para atualizar o valor de conversão:

No Modo Manual, para atualizar o valor de conversão, você precisa usar o método skanUpdateConversionValue. Você pode usá-lo sempre que necessário no ciclo de vida do seu aplicativo.

Observação: O método skanUpdateConversionValue não funcionará se você não tiver ativado o manualSkanConversionManagement.

Método skanUpdateConversionValue
Descrição Atualiza manualmente o valor de conversão da SKAdNetwork.
Assinatura (BOOL)skanUpdateConversionValue:(NSInteger)conversionValue;
Exemplo de uso
SwiftObjective-C
// Envio de um evento padrão para login
Singular.event(EVENT_SNG_LOGIN)
      
// Atualização manual do valor de conversão 
// para 7 após o evento Singular.skanUpdateConversionValue(7)

Outros métodos SKAdNetwork:

Para obter o valor de conversão atual, use o método skanGetConversionValue ou conversionValueUpdatedCallback. Ambos funcionam nos modos gerenciado e manual.

Método skanGetConversionValue
Descrição Obtém o valor de conversão atual rastreado pelo Singular SDK.
Assinatura (NSNumber *)skanGetConversionValue;
Exemplo de uso
SwiftObjective-C
let conversionValue = Singular.skanGetConversionValue()
conversionValueUpdatedCallback Callback
Descrição Obtém o valor de conversão atual rastreado pelo Singular SDK.
Assinatura void(^conversionValueUpdatedCallback)(NSInteger);
Exemplo de uso
SwiftObjective-C
func getConfig() -> SingularConfig? {
// Opções de configuração singulares
guard let config = SingularConfig(apiKey: Constants.APIKEY,
andSecret: Constants.SECRET)
else {
return nil
}
...
config.conversionValueUpdatedCallback = { conversionValue in
// Aqui você tem acesso ao valor de conversão mais recente
}
...
return config }

2.4. Manipulação do consentimento de ATT (definição de um atraso de inicialização)

Exibição de um prompt ATT (App Tracking Transparency)

A partir do iOS 14.5, os aplicativos são obrigados a solicitar o consentimento do usuário (usando a estrutura App Tracking Transparency) antes de poderem acessar e compartilhar alguns dados do usuário que são úteis para fins de rastreamento, incluindo o IDFA do dispositivo.

A Singular se beneficia muito de ter o IDFA para identificar dispositivos e realizar a atribuição de instalações (embora existam maneiras de realizar a atribuição sem o IDFA). Recomendamos enfaticamente que você solicite o consentimento do usuário para obter o IDFA.

Atraso na inicialização para aguardar a resposta da ATT

Por padrão, o Singular SDK envia uma sessão de usuário quando é inicializado. Quando uma sessão é enviada de um novo dispositivo, ela aciona imediatamente o processo de atribuição da Singular - que é realizado com base apenas nos dados disponíveis para a Singular naquele momento. Portanto, é essencial solicitar o consentimento e recuperar o IDFA antes que o SDK da Singular envie a primeira sessão.

Para atrasar o disparo de uma sessão de usuário, inicialize o Singular SDK com a opção waitForTrackingAuthorizationWithTimeoutInterval no objeto Config. Essa opção já está incluída no exemplo de código em 2.2. Criando um objeto de configuração.

SwiftObjective-C
func getConfig() -> SingularConfig? {
guard let config = SingularConfig(apiKey: Constants.APIKEY,
andSecret: Constants.SECRET) else {
return nil
}
... config.waitForTrackingAuthorizationWithTimeoutInterval = 300 ... return config
}

Dica: Quando você define um atraso de inicialização, o fluxo do aplicativo é o seguinte:

  1. Quando o aplicativo é aberto, o Singular SDK começa a gravar uma sessão e os eventos do usuário, mas ainda não os envia para o servidor Singular.
  2. Quando o consentimento do App Tracking Transparency é concedido/negado ou o tempo definido passa, o SDK envia a sessão e quaisquer eventos em fila para o servidor Singular (com ou sem o IDFA).
  3. Em seguida, o Singular inicia o processo de atribuição, aproveitando o IDFA, se ele estiver disponível.
Saiba mais sobre todos os cenários possíveis de ATT

A tabela a seguir resume os cenários possíveis usando essa integração:

Cenário Disponibilidade do IDFA
O usuário vê a caixa de diálogo de consentimento e concede o consentimento antes do término do tempo definido. O IDFA está disponível
O usuário vê a caixa de diálogo de consentimento e nega o consentimento antes do tempo definido. O IDFA não está disponível
O tempo definido expira e, em seguida, o usuário vê a caixa de diálogo de consentimento e concede o consentimento. O IDFA está disponível apenas para os eventos do usuário que são relatados após a concessão do consentimento
O tempo definido expira e, em seguida, o diálogo de consentimento é exibido para o usuário e o consentimento é negado. O IDFA não está disponível
A caixa de diálogo de consentimento é mostrada ao usuário, ele sai do aplicativo sem realizar nenhuma ação e, mais tarde, abre o aplicativo e concede o consentimento após a expiração do tempo definido. Todos os eventos em fila são enviados para o servidor Singular quando o aplicativo é reaberto. O IDFA não está disponível para esses eventos. Todos os eventos rastreados após a concessão do consentimento têm o IDFA associado a eles.
O usuário vê a caixa de diálogo de consentimento, sai do aplicativo sem realizar nenhuma ação e, posteriormente, abre o aplicativo e nega o consentimento. Todos os eventos em fila são enviados aos servidores Singular quando o aplicativo é reaberto. O IDFA não está disponível para esses eventos ou para qualquer um dos eventos rastreados posteriormente.

2.5. Tratamento de deep links

Quando um usuário clica em um deep link em um dispositivo que tem o aplicativo instalado, o aplicativo é aberto e mostra um produto ou uma experiência específica.

Os links de rastreamento da Singular podem incluir a funcionalidade de deep linking, bem como a de deferred deep linking (consulte as Perguntas frequentes sobre deep linking e as Perguntas frequentes sobre links da Singular para obter mais informações).

O Singular SDK Config, implementado na etapa anterior, faz referência a uma função de retorno de chamada ("handleDeeplink"). A função "handleDeeplink" é necessária para habilitar o suporte a deep link e deferred deep link por meio do Singular SDK.

Pré-requisitos para a implementação de deep links

Certifique-se de que você tenha concluído as etapas a seguir:

  • Seguiu as instruções em Pré-requisitos do Singular Links.
  • No Xcode, adicionou um subdomínio personalizado Singular a Signing & Capabilities > Associated Domains.
  • Adicionou o esquema do aplicativo aos seus tipos de URL em Info > URL Types.
  • Adicione seu ID e esquema da equipe de desenvolvedores da Apple na página Apps na plataforma Singular.

Observações:

  • Se o aplicativo já estiver configurado para usar o iOS Universal Links, o domínio do Universal Link já existe em Associated Domains e pode permanecer. Esse domínio deve ser adicionado à opção de configuração Supported Domains, conforme observado na próxima seção.
  • Você também deve incluir o domínio de link personalizado do Singular, para que o Singular possa rastrear atribuições de campanhas de marketing e lidar com links diretos dessas campanhas.

Criação do método de retorno de chamada para o manipulador

O exemplo de código abaixo cria um método de retorno de chamada chamado handleDeeplink (esse método é referenciado no exemplo de código Config acima).

A assinatura do bloco é void(^)(SingularLinkParams*). O SingularLinkParams contém o destino do deep link, os parâmetros de passagem e se o link é diferido ou não.

SwiftObjective-C
func handleDeeplink(params: SingularLinkParams?) {
/* Obter dados de Deeplink do Singular Link */
let deeplink = params?.getDeepLink() let passthrough = params?.getPassthrough() let isDeferredDeeplink = params?.isDeferred() let urlParams = params?.getURLParameters()
// Adicione o código de tratamento de links diretos aqui
// ... }

Outras opções de link

2.6. Inicialização do Singular

Dica: antes de prosseguir, certifique-se de ter concluído as etapas abaixo!

  • Adição da biblioteca Singular
  • Se estiver usando swift: criado um Swift Bridging Header
  • Adicionado código para criar o objeto Singular Config
  • Adicionado um manipulador de deep link
  • Ativou a SKAdNetwork
  • Se estiver exibindo o ATT: adicionado waitForTrackingAuthorizationWithTimeoutInterval
  • Teste de compilação do aplicativo com êxito (o aplicativo deve ser compilado sem erros nesse estágio)

O SDK da Singular deve ser inicializado sempre 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). O SDK é inicializado usando o objeto de configuração que você criou em 2.2. Criação de um objeto de configuração.

Onde adicionar o código de inicialização?

Você precisa inicializar o SDK do Singular em todos os pontos de entrada do aplicativo:

  • Para iOS 13+ usando a interface SwiftUI sem SceneDelegate ou AppDelegate, inicialize o Singular SDK no seguinte ContentView().onOpenURL() e .onChange(of: scenePhase) (veja o código abaixo como exemplo).

  • Para iOS 13+, inicialize o Singular SDK nas seguintes funções SceneDelegate: willConnectTo session, continue userActivity, openURLContexts URLContexts.

  • Para versões mais antigas do iOS que não suportam SceneDelegate, inicialize o SDK nas seguintes funções AppDelegate: didFinishLaunchingWithOptions, continueUserActivity, openURL.

Exemplos de código de inicialização

Para iOS 13+ (Swift SceneDelegate)
// INICIALIZE O SDK NAS SEGUINTES FUNÇÕES DE DELEGADO DE CENÁRIO
// willConnectTo session
func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) { let userActivity = connectionOptions.userActivities.first // Imprimir IDFV no Console para uso no Console do Singular SDK print(Date(), "-- Scene Delegate IDFV:", UIDevice().identifierForVendor!.uuidString as Any)
// Inicialize o Singular SDK aqui: if let config = self.getConfig() { config.userActivity = userActivity Singular.start(config) } } // continue userActivity func scene(_ scene: UIScene, continue userActivity: NSUserActivity) { // Inicia uma nova sessão do Singular em continueUserActivity if let config = self.getConfig() { config.userActivity = userActivity Singular.start(config) } } //openURLContexts URLContexts func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) { // Inicia uma nova sessão do Singular na inicialização a frio a partir do esquema de deeplink if let config = self.getConfig() { config.openUrl = openurlString Singular.start(config) }
// Adicione código personalizado aqui para redirecionar para links diretos não-singulares //... }
Para iOS 13+ (Interface SwiftUI)
// INICIALIZE O SDK NAS SEGUINTES FUNÇÕES DO WINDOWGROUP
var body: some Scene { WindowGroup { ContentView() .onOpenURL(perform: { url in openURL = url // Inicializar o Singular a partir de um openURL if let config = self.getConfig() { config.openUrl = url Singular.start(config) } }) } .onChange(of: scenePhase) { oldValue, phase in // O SwiftUI ScenePhases substitui os antigos eventos do ciclo de vida do SceneDelegate switch phase { case .background: print("Cena do aplicativo: em segundo plano") case .inactive: print("Cena do aplicativo: inativo") case .active: print("Cena do aplicativo: ativo") // Inicializar o Singular if let config = self.getConfig() { Singular.start(config) } @unknown default: print("Cena do aplicativo: desconhecida") } } }
Para iOS 13+ (Objective-C SceneDelegate)
// INICIALIZE O SDK NAS SEGUINTES FUNÇÕES DE DELEGADO DE CENÁRIO
     
// willConnectToSession
- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session
options:(UISceneConnectionOptions *)connectionOptions { NSUserActivity* userActivity = [[[connectionOptions userActivities] allObjects]
firstObject]; // Imprimir o identificador do fornecedor (IDFV) no console do Xcode para uso no console do Singular SDK NSLog(@"-- Scene Delegate IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);
// Iniciar uma nova sessão do Singular a partir de um aplicativo em segundo plano SingularConfig *config = [self getConfig]; config.userActivity = userActivity; [Singular start:config]; } // continueUserActivity
- (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity{ // Inicia uma nova sessão do Singular a partir de um aplicativo em segundo plano SingularConfig *config = [self getConfig]; config.userActivity = userActivity; [Singular start:config]; } // openURLContexts
- (void)scene:(UIScene *)scene openURLContexts:(nonnull NSSet *)URLContexts { // Inicia uma nova sessão do Singular na inicialização a frio a partir do esquema de deeplink SingularConfig *config = [self getConfig]; config.openUrl = url; [Singular start:config]; // Adicionar código personalizado aqui para redirecionar para links profundos não-singulares //... }
Para versões mais antigas do iOS (Objective-C AppDelegate)
// INICIALIZE O SDK NAS SEGUINTES FUNÇÕES APPDELEGATE
    
// didFinishLaunchingWithOptions
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { // Inicia uma nova sessão quando o usuário abre o aplicativo se o tempo limite da sessão tiver passado/aberto usando o Singular Link SingularConfig *config = [self getConfig]; config.launchOptions = launchOptions; [Singular start:config]; return YES; } // continueUserActivity
- (BOOL)application:(UIApplication *)application
continueUserActivity:(NSUserActivity *)userActivity
restorationHandler:(void (^)(NSArray<id> *restorableObjects))restorationHandler { // Inicia uma nova sessão quando o usuário abre o aplicativo usando um Singular Link enquanto ele estava em segundo plano SingularConfig *config = [self getConfig]; config.userActivity = userActivity; [Singular start:config]; return YES; } // openURL
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options{ // Inicia uma nova sessão quando o usuário abre o aplicativo usando um link não-singular, como um esquema de aplicativo tradicional. SingularConfig *config = [self getConfig]; config.openUrl = url; [Singular start:config]; // Adicione código personalizado aqui para redirecionar para links diretos não-singulares //... return YES; }

Observações:

  • Ao criar o objeto config, tenha cuidado para passar a opção correta - userActivity ou openUrl. Veja o código de exemplo abaixo e consulte os aplicativos de exemplo, se necessário.
  • Lembre-se de cumprir as várias leis de privacidade promulgadas nas regiões onde você faz negócios, incluindo GDPR, CCPA e COPPA. Para obter mais informações, consulte Práticas de Opt-In e Opt-Out do SDK e analise as funções do Singular SDK que o ajudam a cumprir as leis de privacidade de dados.
  • 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".

2.7. 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étodos setCustomUserId e unsetCustomUserId
Descrição Define e desinstala a ID do usuário.
Assinatura (void)setCustomUserId:(NSString*)customUserId
(void)unsetCustomUserId;
Exemplo de uso
SwiftObjective-C
setCustomUserId("custom_user_id")
unsetCustomUserId()
Opcional: Mapeamento de 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 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
SwiftObjective-C
setDeviceCustomUserId("custom_user_id")

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

O SDK da Singular permite que você defina propriedades personalizadas a serem enviadas aos servidores da Singular junto 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/status do aplicativo ou qualquer outra coisa.

Você pode definir até 5 propriedades globais. Elas persistem entre as execuções do aplicativo (com o valor mais recente que você forneceu a elas) até que você as desfaça ou o usuário desinstale o aplicativo.

Casos de uso

Alguns casos de uso de propriedades globais são:

  • Passar um identificador de um SDK de terceiros e, em seguida, usá-lo em um postback do Singular para esse terceiro para fins de correspondência.
  • Em um aplicativo de jogos, você pode definir uma propriedade chamada "Level" e defini-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, você redefinirá a propriedade para "1" e assim por diante.

Observações:

  • Atualmente, as propriedades globais são refletidas nos logs de eventos em nível de usuário do Singular (consulte Exportando logs de atribuição) e em postbacks. O suporte para propriedades globais nos relatórios agregados da Singular (a página Relatórios ou a API de relatórios) será adicionado no futuro. Se tiver dúvidas sobre esse recurso ou estiver interessado em atualizações do suporte a propriedades globais, entre em contato com o gerente de sucesso do cliente da Singular.
  • 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 para 200 caracteres.

Definição de propriedades globais por meio do objeto Config

Para definir as propriedades globais antes de inicializar o SDK, use o método setGlobalProperty no objeto Config.

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.

Método setGlobalProperty
Descrição Define uma propriedade global.
Assinatura (void)setGlobalProperty:(NSString*)key withValue:(NSString*)value overrideExisting:(BOOL)overrideExisiting;
Exemplo de uso
SwiftObjective-C
func getConfig() -> SingularConfig? {
// (Opcional) Obtenha identificadores de terceiros para definir
// em Propriedades globais: // Se SDKs de terceiros estiverem fornecendo identificadores ao Singular,
// o respectivo SDK deverá ser inicializado antes do Singular. let thirdPartyKey = "anonymousID" let thirdPartyID = "2ed20738-059d-42b5-ab80-5aa0c530e3e1" // Opções de configuração singulares guard let config = SingularConfig(
apiKey: Constants.APIKEY, andSecret: Constants.SECRET) else { return nil }
... // Uso do recurso Singular Global Properties para capturar identificadores
// de terceiros config.setGlobalProperty(thirdPartyKey, withValue: thirdPartyID, overrideExisting: true) ... return config }

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

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

Observações:

  • Se a propriedade ainda não existir e já houver 5 outras propriedades globais, a propriedade não será adicionada.
  • Se a propriedade já tiver sido definida, o parâmetro overrideExisting determinará se o valor existente será substituído.
  • O método retornará true se a propriedade tiver sido definida com êxito ou false caso contrário.
Método setGlobalProperty
Descrição Define uma propriedade global para um determinado valor.
Assinatura (BOOL) setGlobalProperty:(NSString*)key andValue:(NSString*)value overrideExisting:(BOOL)overrideExisting
Exemplo de uso
SwiftObjective-C
var result = Singular.setGlobalProperty(
"propertyName", andValue:
"propertyValue", overrideExisting: true)
Método getGlobalProperties
Descrição Recupera todas as propriedades globais e seus valores atuais como um mapa.
Assinatura NSDictionary*) getGlobalProperties
Exemplo de uso
SwiftObjective-C
var globalProperties = Singular.getGlobalProperties()
Método unsetGlobalProperty
Descrição Remove uma propriedade global.
Assinatura (void) unsetGlobalProperty:(NSString*)key
Exemplo de uso
SwiftObjective-C
Singular.unsetGlobalProperty("propertyName")
Método clearGlobalProperties
Descrição Remove todas as propriedades globais.
Assinatura (void) clearGlobalProperties
Exemplo de uso
SwiftObjective-C
Singular.clearGlobalProperties()

2.9. Modificação do tempo limite da sessão (opcional)

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 esse valor de tempo limite, use o método setSessionTimeout e adicione-o ao Config.

setSessionTimeout Método
Descrição Altera o valor de tempo limite da sessão.
Assinatura (void)setSessionTimeout:(int)timeout
Exemplo de uso
SwiftObjective-C
 func getConfig() -> SingularConfig? {
// Opções de configuração singulares guard let config = SingularConfig(
apiKey: Constants.APIKEY, andSecret: Constants.SECRET) else {
return nil } ... Singular.setSessionTimeout(120) ... return config }

3. Rastreamento de eventos e receita

Observação: para obter detalhes sobre o planejamento de eventos de usuários, consulte O aplicativo rastreará os eventos do usuário? no guia Planejamento e pré-requisitos do SDK.

Observação: recomendamos o envio de todos os eventos no aplicativo para o servidor Singular usando os métodos do SDK Singular em seu aplicativo. Se você planeja enviar eventos para a Singular a partir de outro provedor ou de um servidor interno, consulte a seção Rastreamento de eventos híbridos abaixo.

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.

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 seus KPIs de marketing.

Para obter mais detalhes sobre o planejamento de eventos de usuário, consulte O aplicativo rastreará eventos de usuário? no guia Planejamento e pré-requisitos do SDK.

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

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

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.

evento Método
Descrição Envia um evento de usuário para a Singular para rastreamento.
Assinatura (void)event:(NSString *)name
Exemplo de uso
SwiftObjective-C
Singular.event(EVENT_SNG_LOGIN);
Método eventWithArgs
Descrição Envia um evento de usuário ao Singular para rastreamento, com informações adicionais.
Assinatura (void)eventWithArgs:(NSString *)name, ...
Exemplo de uso O exemplo a seguir envia um evento Content View com os atributos padrão recomendados.
SwiftObjective-C
dic[ATTRIBUTE_SNG_ATTR_CONTENT_TYPE] = "PrivacyController"
dic[ATTRIBUTE_SNG_ATTR_CONTENT_ID] = "0" dic[ATTRIBUTE_SNG_ATTR_CONTENT] = "GDPR and CCPA Opt-Out Options" Singular.event(EVENT_SNG_CONTENT_VIEW, withArgs: dic)

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 em relatórios, exportação de registros e postbacks.

Observação: Se seu aplicativo for compatível com o rastreamento de IAP por meio da App Store, esse método é recomendado.Se você não estiver usando o IAP da App Store, consulte os métodos alternativos abaixo.

Relatório de receita por meio do rastreamento de IAP (recomendado)

Para relatar eventos de receita à Singular, use o método iapComplete SDK. Esse método envia um evento de receita de IAP(compra no aplicativo da Apple) para a Singular com:

  • Todos os detalhes da transação, que a Singular usará para enriquecer os relatórios.
  • O recibo da transação, que pode ser usado para validar a transação e analisar ou evitar tentativas de fraude.

Observações:

  • Ao usar o iapComplete, você deve incluir o objeto SKPaymentTransaction no evento.
  • Qualquer receita informada em uma moeda diferente será convertida automaticamente para a moeda preferencial da sua organização, conforme definido na sua conta do Singular.
Método iapComplete
Descrição Envia um evento de receita para a Singular com o recibo da transação.
Assinatura (void)iapComplete:(id)transaction (void)iapComplete:(id)transaction withName:(NSString *)name;
Exemplo de uso
SwiftObjective-C
// *** Obter o objeto de transação SKPaymentTransaction* ***
let transaction:SKPaymentTransaction = ...

// Enviar um evento de transação para a Singular sem um nome de
// evento personalizado Singular.iapComplete(transaction) // Enviar um evento de transação para a Singular com um nome de
// evento personalizado Singular.iapComplete(transaction, withName:"MyCustomRevenue")

Relatório de evento de receita alternativo

Embora a Singular recomende o uso do iapComplete, também fornecemos dois métodos alternativos para relatar eventos de receita à Singular, caso seu aplicativo não use o rastreamento de IAP da App Store.

Os métodos Revenue e CustomRevenue

Os métodos revenue e customRevenue permitem que você especifique o valor da transação e a moeda manualmente, bem como detalhes adicionais opcionais, como o número de série e a quantidade do produto, etc. O método customRevenue também permite que você passe um nome de evento personalizado.

Observe que, se você usar esses métodos, a Singular não obterá o recibo da transação e não poderá validá-la.

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

receita Método
Descrição

Envie um evento de receita para a Singular com o valor e a moeda da receita

e detalhes adicionais opcionais.

Assinatura

(void)revenue:(NSString *)currency amount:(double)amount;

(void)revenue:(NSString *)currency amount:(double)amount productSKU:(NSString *)productSKU

  productName:(NSString *)productName productCategory:(NSString *)productCategory

  productQuantity:(int)productQuantity productPrice:(double)productPrice;

(void)revenue:(NSString *)currency amount:(double)amount withAttributes:(NSDictionary*)attributes;

Exemplo de uso
SwiftObjective-C
// Receita sem detalhes do produto
Singular.revenue("USD",amount:1.99)

// Receita com detalhes do produto Singular.revenue("EUR",amount:5.00, productSKU:"SKU1928375", productName:"Reservation Fee",productCategory:"Fee", productQuantity:1,
productPrice:5.00)
// Enviar um Revenue Event com atributos em um dicionário var dic: [AnyHashable : Any] = [:] dic[ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION] = "100% Organic Cotton Mixed Plaid Flannel Shirt" dic[ATTRIBUTE_SNG_ATTR_ITEM_PRICE] = "$69.95" dic[ATTRIBUTE_SNG_ATTR_RATING] = "5 Star" dic[ATTRIBUTE_SNG_ATTR_SEARCH_STRING] = "Flannel Shirt" Singular.revenue("USD", amount: 19.95, withAttributes: dic)
Método customRevenue
Descrição

Envia um evento de receita para a Singular com um nome de evento, bem como o valor

e a moeda da receita e detalhes adicionais opcionais.

Assinatura

(void)customRevenue:(NSString *)eventName currency:(NSString *)currency

  amount:(double)amount;

(void)customRevenue:(NSString *)eventName currency:(NSString *)currency amount:(double)amount

  productSKU:(NSString *)productSKU productName:(NSString *)productName 

  productCategory:(NSString *)productCategory productQuantity:(int)productQuantity

  productPrice:(double)productPrice;

(void)customRevenue:(NSString*)eventname currency:(NSString *)currency amount:(double)amount

  withAttributes:(NSDictionary*)attributes;

Exemplo de uso
SwiftObjective-C
// Receita com um nome personalizado e sem detalhes do produto
Singular.customRevenue("MyCustomRevenue", currency:"USD", amount:1.99)
// Receita com um nome personalizado e detalhes do produto Singular.customRevenue("MyCustomRevenue", currency:"EUR", amount:5.00,
productSKU:"SKU1928375", productName:"Reservation Fee", productCategory:"Fee", productQuantity:1, productPrice:5.00)
// Enviar um evento de receita personalizado com atributos em um dicionário var dic: [AnyHashable : Any] = [:] dic[ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION] = "100% Organic Cotton Mixed Plaid Flannel Shirt" dic[ATTRIBUTE_SNG_ATTR_ITEM_PRICE] = "$69.95" dic[ATTRIBUTE_SNG_ATTR_RATING] = "5 Star" dic[ATTRIBUTE_SNG_ATTR_SEARCH_STRING] = "Flannel Shirt" Singular.customRevenue("CustomRevenueWithArgsDic", currency: "USD", amount: 44.99, withAttributes: dic)

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.

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.

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 11.0.8+ do SDK.

Use o método createReferrerShortLink para gerar um link de compartilhamento abreviado para o usuário compartilhar o aplicativo com amigos. Defina os detalhes do usuário de referência no código do aplicativo quando o link for criado. Isso permite rastrear as atribuições do referenciador nos relatórios.

Para criar um link curto:

  1. Crie um link de origem personalizado singular com links profundos definidos, que leve ao download do aplicativo (consulte as Perguntas frequentes sobre links singulares). Esse link será chamado de link de base no código abaixo.
  2. Quaisquer parâmetros de substituição de campanha para adicionar ao link dinamicamente (consulte Parâmetros de link de rastreamento para obter a lista de opções).
  3. O nome e o ID do usuário de referência, a fim de rastrear novas instalações de aplicativos até o usuário que compartilhou o link.

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

createReferrerShortLink Método
Descrição Use o método createReferrerShortLink para gerar um link de compartilhamento abreviado para o usuário compartilhar o aplicativo com amigos.
Assinatura (void)createReferrerShortLink:(NSString *)baseLink referrerName:(NSString *)referrerName referrerId:(NSString *)referrerId passthroughParams:(NSDictionary *)passthroughParams completionHandler:(void(^)(NSString *, NSError *))completionHandler;
Exemplo de uso
SwiftObjective-C
// 1. Definir variáveis para o link curto do referenciador
// Defina seu link de rastreamento Singular para ser usado como um link de base: let referrerBaseLink = "https://yourdomain.sng.link/Csfge/aknl?_dl=myscheme%3A%2F%2Fmydeeplink/referrer&_smtype=3";
// Adicione seu ID e nome do referenciador let referrerID = referrerIDField.text; let referrerName = referrerNameField.text;
// Personalizar quaisquer parâmetros de passagem let passthroughParams = ["channel": "sms"] // 2. Chame o ReferrerShortLink para obter seu link curto para
// compartilhar nas mídias sociais Singular.createReferrerShortLink(referrerBaseLink, referrerName: referrerName, referrerId: referrerID, passthroughParams: passthroughParams, completionHandler: {(shortLink, error) in if error != nil {
// Lógica para tentar novamente/abortar/modificar os parâmetros passados para a função, com base na causa do erro } if (shortLink != nil || shortLink != "") { // Adicione sua lógica de compartilhamento aqui: ... } })

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

Observação: A partir da versão 11.0.0 do SDK, a Singular adicionou a opção de configurar a atribuição de receita de anúncios por meio do SDK da Singular. A atribuição de receita de anúncios ainda pode ser configurada usando chamadas de API, sem atualizar o Singular SDK nos aplicativos. No entanto, se você quiser medir a receita de anúncios para campanhas SKAdNetwork, será necessário configurar a atribuição de receita de anúncios por meio do SDK.

Para adicionar suporte à atribuição de receita de anúncios no SDK da Singular:

  1. Certifique-se de que esteja usando a versão mais recente do SDK da Singular.
  2. Adicione o trecho de código apropriado à sua integração do Singular SDK, dependendo da plataforma de mediação usada para dados de receita de anúncios.

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

AdMob
  1. Observação: Esse recurso precisa ser ativado em sua conta da Admob.

    Consulte https://support.google.com/admob/answer/11322405#getstarted

SwiftObjective-C
var rewardedAd: GADRewardedAd?
GADRewardedAd.load(withAdUnitID: "AD_UNIT_ID", request: request) { 
[weak self] ad, error in guard let self = self else { return } if let error = error { print("O anúncio premiado não foi carregado com erro: \(error.localizedDescription)") return } self.rewardedAd = ad self.rewardedAd?.paidEventHandler = { adValue in let impressionData = adValue let data = SingularAdData(
adPlatform: "Admob", currency: impressionData.currencyCode, revenue: impressionData.value) }
}
AppLovinMax
  1. Recuperar o objeto recebido do evento do AppLovin MAX, didReceivedMessage
SwiftObjective-C
if let message = message {
   let data = SingularAdData(
adPlatform: "AppLovin", currency: "USD", revenue: message.data["revenue"] as? Double ?? 0.0) Singular.adRevenue(data) }
IronSource
  1. Recupere o objeto recebido do evento do IronSource, impressionDataDidSucceed
  2. Certifique-se de que o sinalizador ARM SDK Postbacks no IronSource esteja ativado
  3. Consulte https://developers.is.com/ironsource-mobile/general/ad-revenue-measurement-postbacks/#step-1
SwiftObjective-C
if let impressionData = impressionData {
   let data = SingularAdData(
adPlatform: "IronSource", currency: "USD", revenue: impressionData.revenue) Singular.adRevenue(data) }
TradPlus
  1. Defina o impressionDelegate
  2. Adicionar Singular ao retorno de chamada TradPlusAdImpression
SwiftObjective-C
TradPlus.sharedInstance().impressionDelegate = self

func tradPlusAdImpression(_ adInfo: [AnyHashable: Any]?) { guard let adInfo = adInfo else { return } let currency = "USD" if let ecpm = adInfo["ecpm"] as? Float { let revenue = CGFloat(ecpm) / 1000.0 let data = SingularAdData(adPlatform: "TradPlus", currency: currency, revenue: revenue) Singular.adRevenue(data) }
}
Outros (genéricos)
  1. Inicializar o objeto SingularAdData com os dados relevantes
  2. Informar os dados ao Singular
SwiftObjective-C
let data = SingularAdData(
adPlatform: "SUA_PLATAFORMA_DE_ANÚNCIOS", currency: "CÓDIGO DA MOEDA", revenue: 9.90) Singular.adRevenue(data)

4.3. Rastreamento de desinstalações

Observação: o rastreamento de desinstalação só está disponível para clientes Enterprise. Além disso, o rastreamento de desinstalações exige que o aplicativo seja compatível com notificações por push. Consulte o guia da Apple para implementar o APNS.

Para configurar o rastreamento de desinstalação:

  1. Habilite o aplicativo na Singular seguindo o guia: Configurando o rastreamento de instalação do iOS.
  2. No aplicativo, envie ao Singular o token do dispositivo retornado do Apple Push Notification Service (APNS). Para passar o token do dispositivo para o Singular, use o método registerDeviceTokenForUninstall ou registerDeviceToken. Faça isso antes que o SDK da Singular seja inicializado. Isso deve ser chamado a partir do método AppDelegate didRegisterForRemoteNotificationsWithDeviceToken.

Observação: se você já estiver recuperando um token de dispositivo de uma implementação de notificação por push existente, poderá usar esse valor.

O token APNS geralmente é um dado binário no formato nativo. Passe o token conforme recebido do APNS. Se o aplicativo alterar o tipo de dados do token, passe-o como uma cadeia de caracteres codificada em hexadecimal, por exemplo: b0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052

Método registerDeviceTokenForUninstall
Descrição Passa o token do dispositivo retornado do APNS.
Assinatura + (void)registerDeviceTokenForUninstall:(NSData*)deviceToken;
Exemplo de uso
SwiftObjective-C
func application(_ application: UIApplication, 
  didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  // Enviar o deviceToken para a Singular para rastreamento da desinstalação   
  Singular.registerDeviceToken(forUninstall: deviceToken) 
} 

4.4. Interface JavaScript do SDK da Singular

A Singular fornece uma interface JavaScript que você pode usar para chamar a Singular 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:

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

Métodos suportados em JavaScript

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

  • setCustomUserID
  • unsetCustomUserID
  • event
  • revenue

Ativação da interface JavaScript

Observação: a partir do iOS 8.0+, a Apple recomenda o uso do WKWebView para adicionar conteúdo da Web ao seu aplicativo. Não use o UIWebView ou o WebView. Consulte a documentação do WKWebView da Apple para obter mais informações.

Para ativar a interface JavaScript ao usar o WKWebView, você precisa adicionar algum código ao método webView do protocolo WKNavigationDelegate (esse protocolo ajuda a implementar comportamentos personalizados acionados quando uma visualização da Web manipula uma solicitação de navegação).

Rápido
extension ViewController: WKNavigationDelegate { 
    func webView(_: WKWebView, decidePolicyFor: WKNavigationAction, 
      decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) { 
      // Manipulador singular 
      let js = "typeof(Singular)" 
       webView.evaluateJavaScript(js) { (result, error) -> Void in 
         if let resultString = result as? String { 
           if resultString.isEqual("undefined") { 
             do { 
               let contents = try String(contentsOfFile: 
               Bundle.main.path(forResource: "Singular", ofType: "js")!) 
               self.webView.evaluateJavaScript(contents, completionHandler: nil) 
             } catch { } 
           }
           else { 
             print(decidePolicyFor.request) 
             Singular.processJSRequestWK(self.webView, withURL:decidePolicyFor.request) 
           } 
         }  
       } 
       // O restante de seu código está aqui  
    }
  }

5. Conformidade com as leis de privacidade de dados

A Singular fornece a funcionalidade de proteção da 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.

5.1. Limite o compartilhamento de dados

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 limitDataSharing:NO para indicar que o usuário consentiu (optou por participar) em compartilhar suas informações.
  • Use limitDataSharing:YES 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 limitDataSharing
Descrição Notifica a Singular sobre o consentimento do usuário (opt-in) para o compartilhamento de dados privados.
Assinatura (void)limitDataSharing:(BOOL)shouldLimitDataSharing;
Exemplo de uso
SwiftObjective-C
// O usuário optou por compartilhar
data Singular.limitDataSharing(false) 

5.2. 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 trackingOptIn
Descrição Notifica a Singular sobre o consentimento do usuário para rastreamento (opt-in).
Assinatura (void)trackingOptIn;
Exemplo de uso
SwiftObjective-C
Singular.trackingOptIn() 
Método stopAllTracking
Descrição Interrompe todas as atividades de rastreamento para este usuário neste aplicativo.
Assinatura (void)stopAllTracking;
Exemplo de uso

Importante: chamar esse método desativa o SDK, mesmo entre as reinicializações do aplicativo (o estado é persistente). A única maneira de desativá-lo é chamando o método resumeAllTracking.

SwiftObjective-C
Singular.stopAllTracking() 
Método resumeAllTracking
Descrição Retoma as atividades de rastreamento para esse usuário neste aplicativo.
Assinatura (void)resumeAllTracking;
Exemplo de uso
SwiftObjective-C
Singular.resumeAllTracking() 
Método isAllTrackingStopped
Descrição Verifica o status das atividades de rastreamento para este usuário neste aplicativo.
Assinatura (BOOL)isAllTrackingStopped;
Exemplo de uso
SwiftObjective-C
Singular.isAllTrackingStopped()
// retorna verdadeiro/falso

6. Perguntas e problemas frequentes

Consulte esta seção se encontrar algum problema ou erro ao criar seu aplicativo de teste.

Por que estou recebendo um erro "Sandbox: rsync.samba(15813) deny(1) file-read-data..."?

No Xcode 15, há uma nova opção chamada "User Script Sandboxing" que desempenha um papel crucial na compilação. O objetivo é evitar que os scripts façam alterações não intencionais no sistema, aumentando assim a estabilidade e a segurança da compilação. Quando ativado, o sistema de compilação restringe os scripts do usuário para não permitir dependências de entrada/saída não declaradas. Isso é problemático para o Singular SDK, pois ele precisa executar scripts para vincular dependências de forma dinâmica.

Para resolver o problema:

  1. Navegue até Build Settings > Build Options.
  2. Ajuste "User Script Sandboxing" para um valor "No"
Por que estou recebendo um erro "No module named Singular"?
  1. Verifique se o Bridging Header foi criado.
  2. Valide se o arquivo Bridging Header está vinculado em Build Settings > Objective-C Bridging Header.
Por que estou recebendo um erro de compilação "Arm64"?

Em alguns casos, o Simulador do iOS exige que o arm64 seja excluído em Build Settings > Excluded Architectures.

excluded_architectures_arm64.png

Implementei as propriedades globais. Por que não as estou vendo no Console de teste?

No momento, as propriedades globais não são exibidas no Console de teste. Elas serão adicionadas no futuro. Use Export Logs para validar essa funcionalidade.

Por que estou recebendo o seguinte erro no console do Xcode: "SKAdNetwork: Erro ao atualizar o valor de conversão: Error Domain=SKANErrorDomain Code=10"?

Você pode ignorar esse erro, pois ele é esperado quando a SKAdNetwork não viu uma impressão de uma campanha (consulte a resposta da Apple a essa pergunta).

Por que estou recebendo um erro de registro?

Os erros de registro comuns a seguir podem ser ignorados:

  • [logging] duplicate column name: singular_link in "ALTER TABLE sessions ADD COLUMN singular_link TEXT DEFAULT NULL"
  • [logging] duplicate column name: payload in "ALTER TABLE sessions ADD COLUMN payload TEXT DEFAULT NULL"
  • [logging] duplicate column name: sequence in "ALTER TABLE events ADD COLUMN sequence INTEGER DEFAULT -1"
  • [logging] duplicate column name: payload in "ALTER TABLE events ADD COLUMN payload TEXT DEFAULT NULL"