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 a 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 captura eventos de receita de compras in-app (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 de campanhas, proporcionando flexibilidade na forma como os dados são consumidos e analisados.

Requisitos

  • Se forem utilizados nomes personalizados de eventos de receitas, os nomes personalizados de eventos de receitas estão limitados a 32 caracteres ASCII. Para caracteres não-ASCII, o limite é de 32 bytes depois de convertidos para UTF-8.
  • Os nomes e valores de atributos de eventos estão limitados a 500 caracteres ASCII.
  • Passe a moeda como um código de moeda ISO 4217 de três letras:

    USD, EUR, INR

Melhores práticas

  • A Singular recomenda transmitir eventos usando a convenção de nomenclatura de eventos e atributos padrão da Singular.
  • Se forem usados nomes personalizados de eventos de receita, eles devem ser enviados em inglês para melhorar a compatibilidade com postbacks da rede de anúncios.
  • Os eventos de receita só devem ser enviados para a Singular quando o valor da receita for maior ou menor que 0.

Implementações de rastreamento de receita

Compra no aplicativo

Compra no aplicativo

Importante: Este método não é compatível com o rastreamento de Assinatura! Utilize este método para o acompanhamento de compras na aplicação sem subscrição.

Se a sua aplicação utiliza o rastreio de IAP da App Store, recomenda-se a utilização do método iapComplete.

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 o Singular usará para enriquecer os relatórios.
  • O recibo da transação, que será usado para validar a transação e analisar ou evitar tentativas de fraude.

Observações:

  • Ao utilizar o iapComplete, é necessário incluir o objetoSKPaymentTransaction no evento.
  • Qualquer receita reportada numa moeda diferente será convertida automaticamente para a moeda preferida da sua organização, conforme definido na sua conta Singular.

Método iapComplete

Envia um evento de receita para a Singular com o recibo da transação.

Assinaturas

(void)iapComplete:(id)transaction

(void)iapComplete:(id)transaction withName:(NSString *)name;

Exemplos de uso

SwiftObjective-C
// *** Get the SKPaymentTransaction* transaction object ***

let transaction:SKPaymentTransaction = ...

// Send a transaction event to Singular without a custom event name

Singular.iapComplete(transaction)

// Send a transaction event to Singular with a custom event name

Singular.iapComplete(transaction, withName:"MyCustomRevenue")
Receita de assinatura

Receita de assinatura

Acompanhamento de assinaturas:

O Singular permite que você rastreie suas assinaturas e renovações dentro do seu aplicativo, fornecendo insights sobre o comportamento do usuário e geração de receita. Consulte nosso guia abrangente sobre como implementar eventos de assinatura usando o SDK do Singular.[Guia de implementação técnica de eventos de assinatura].

Receita personalizada sem validação de compra

Receita personalizada sem validação de compra

Se o seu aplicativo não suporta o rastreamento de compras no aplicativo da App Store, os métodos revenue ou customRevenue são recomendados. Estes métodos não efectuam a validação da compra e não devem incluir o objeto de compra ou o recibo.

Os métodos revenue e customRevenue permitem-lhe especificar manualmente o montante da transação e a moeda, 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-lhe passar um nome de evento personalizado.

Nota: se utilizar estes métodos, o Singular não valida a transação de compra.


Método revenue

Envia um evento de receita para a Singular com o valor da receita, moeda e detalhes opcionais.

Assinaturas

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

Exemplos de uso

SwiftObjective-C
// Revenue with no product details

Singular.revenue("USD", amount:1.99)

// Revenue with product details

Singular.revenue("EUR", amount:5.00, 
     productSKU:"SKU1928375", 
     productName:"Reservation Fee",
     productCategory:"Fee", 
     productQuantity:1, productPrice:5.00)

// Send a Revenue Event with attributes in a dictionary

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

Envia eventos de receita personalizados para a Singular, especificando o nome do evento, o valor da receita, o código da moeda e quaisquer atributos de transação adicionais. A Singular processa esses eventos para rastrear a receita in-app.

Assinaturas

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

Exemplos de uso

SwiftObjective-C
// Revenue with a custom name and no product details

Singular.customRevenue("MyCustomRevenue", currency:"USD", amount:1.99)

// Revenue with a custom name and product details

Singular.customRevenue("MyCustomRevenue", currency:"EUR", amount:5.00, 
     productSKU:"SKU1928375", 
     productName:"Reservation Fee", 
     productCategory:"Fee", 
     productQuantity:1, 
     productPrice:5.00)

// Send a Custom Revenue Event with attributes in a dictionary

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)
Suporte do StoreKit2

Suporte do StoreKit2

Se o seu aplicativo usa a estrutura do StoreKit2 para rastreamento de compras no aplicativo, o método customRevenue é recomendado. O método customRevenue requer que forneça a transação e o objeto de produto em jsonRepresentation.

A validação de compra não é suportada para o StoreKit2


Método customRevenue

Assinaturas

+ (void)customRevenue:(NSData *)transactionJsonRepresentation productJsonRepresentation:(NSData *)productJsonRepresentation;

+ (void)customRevenue:(NSString *)eventName transactionJsonRepresentation:(NSData *)transactionJsonRepresentation productJsonRepresentation:(NSData *)productJsonRepresentation;

Exemplos de uso

SwiftObjective-C
// Fetch transaction and product from StoreKit2

let transaction = ... // Assume this is a valid StoreKit2 transaction

let product = ... // Assume this is a valid StoreKit2 product


// Custom Revenue using __iap__ event name with transaction and product JSON representations

Singular.customRevenue(
            transactionJsonRepresentation: transaction.jsonRepresentation, 
            productJsonRepresentation: product.jsonRepresentation )

// Custom Revenue with custom event name using transaction and product JSON representations

Singular.customRevenue(
            "PaymentSuccess", 
            transactionJsonRepresentation: transaction.jsonRepresentation, 
            productJsonRepresentation: product.jsonRepresentation )
}

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

A Singular está integrada a plataformas de mediação, como Google AdMob, AppLovin, Unity LevelPlay (IronSource) e TradPlus, para atribuição de receita de anúncios. A Singular também oferece suporte a outras plataformas de mediação por meio de nossa integração genérica de SDK de receita de anúncios.

Você pode obter dados de atribuição de receita de anúncios de sua plataforma de mediação adicionando um trecho de código à integração do Singular SDK. Isso também permite que você obtenha dados de receita de anúncios para campanhas de SKAdNetwork.

A obtenção de receita de anúncios no nível do usuário a partir de sua plataforma de mediação permite que a Singular envie a receita de anúncios atribuída de volta às fontes de mídia que podem aceitar esses dados para executar campanhas AdROAS.

Consulte as instruções e os trechos de código para a implementação do SDK [AQUI].

4.3. Rastreamento de desinstalações

Observação: Para usar o rastreamento de desinstalação de aplicativos, seu aplicativo deve ser compatível com notificações 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 Notifique Singular sobre o consentimento do usuário (opt-in) para compartilhar dados privados. O método Limitar compartilhamento de dados oferece uma opção para controlar se o seu aplicativo envia dados do usuário a terceiros. Isso é útil se você quiser restringir o compartilhamento de dados com base nas preferências do usuário ou nos requisitos de privacidade.
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 Notificar a Singular sobre o consentimento do usuário (opt-in) para rastreamento. O método TrackingOptIn() é usado para enviar um evento “gdpr” para os servidores da Singular. Se você não chamar esse método, o aplicativo continuará a rastrear os usuários como se eles tivessem dado consentimento, mas não os marcará especificamente como opt-in do GDPR. Se o seu aplicativo precisar estar em conformidade com o GDPR (Regulamento Geral de Proteção de Dados), você deverá chamar essa função para garantir que o consentimento do usuário seja registrado corretamente.
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"