Integração do SDK da AppsFlyer - iOS

  • Anunciantes
  • Desenvolvedores

ios.pngVersão do SDK: 4.10.0 (Notas de versão)

1. Visão geral

This guide details how to integrate AppsFlyer's SDK into your iOS app. You can record installs, updates, sessions, and additional in-app events as well as app installs (including in-app purchases, game levels, etc.) to evaluate ROI and user engagement levels. The iOS SDK is compatible with all iOS devices (iPhone, iPod, iPad) with iOS version 6 and later.

 Observação

O SDK da AppsFlyer está em total conformidade com as redes NAT64/DNS64 com IPv6 da Apple. Para mais informações, clique aqui.

 Importante!

O SDK da AppsFlyer utiliza a classe NSUserDefaults. Limpar todos os valores da NSUserDefaults pode causar problemas de atribuição.

 Dica

  • In order to implement basic SDK integration that is, install attribution only, it is mandatory to complete the procedures in sections 2 and 3 in this document. 
  • It is recommended that you read the Recording in-app events section as an aid to implementation
  • The rest of the described features described, are optional and implementing them will depend on your app's business logic. For example, recording revenue or getting the conversion data on first launch may be vital for your app's flow

2. Início rápido

2.1 Baixar e adicionar o SDK da AppsFlyer ao Xcode

CocoaPodsCarthageStatic FrameworkStatic Lib
  1. Certifique-se de ter baixado e instalado a versão mais recente do CocoaPods.
  2. Adicione a linha a seguir ao seu Podfile:
    pod 'AppsFlyerFramework'
  3. execute o pod install
  4. Certifique-se de usar o arquivo .xcworkspace para abrir seu projeto no Xcode, em vez do arquivo .xcodeproj, daqui em diante.

O SDK da AppsFlyer utiliza as seguintes estruturas nativas:

AdSupport.framework
Essa estrutura é necessária para coletar o IDFA dos dispositivos.
Sem o IDFA você não consegue atribuir instalações aos anúncios do Facebook, Twitter, Google e outras redes.
iAd.framework
Essa estrutura é necessária para gravar e medir o desempenho dos anúncios da Apple Search em seu aplicativo

2.2 Configurar integração no App Delegate

SwiftObjective-C

Em AppDelegate.swift, faça o seguinte:

  1. importe a AppsFlyerLib
  2. Adicione AppsFlyerTrackerDelegate à declaração de classe
import AppsFlyerLib
class AppDelegate: UIResponder, UIApplicationDelegate, AppsFlyerTrackerDelegate {
   // your code here
}

3. Inicialização do SDK

Inicialize o SDK usando o método didFinishLaunchingWithOptions com a ID do aplicativo retirada do iTunes Connect e sua dev key da AppsFlyer

Observe que aqui você precisa definir a ID do aplicativo apenas com dígitos, sem o prefixo "id".

SwiftObjective-C
AppsFlyerTracker.shared().appsFlyerDevKey = "<your-appsflyer-dev-key>";
AppsFlyerTracker.shared().appleAppID = "123456789"
AppsFlyerTracker.shared().delegate = self
#if DEBUG AppsFlyerTracker.shared().isDebug = true
#endif

 Observação

Se isDebug=true estiver definido, os logs do SDK da AppsFlyer são mostrados no console do xCode

 

  • Adicione o código a seguir na função applicationDidBecomeActive:
SwiftObjective-C
func applicationDidBecomeActive(application: UIApplication) { 
// attribute Installs, updates & sessions(app opens) 
// (You must include this API to enable SDK functions) 
AppsFlyerTracker.shared().trackAppLaunch() 
// your other code here.... }

Verificando se o acompanhamento de inicializações do aplicativo foi bem-sucedido

Você pode verificar se a solicitação para acompanhar as inicializações do aplicativo foi bem-sucedida implementando trackAppLaunchWithCompletionHandler. Em seguida, você pode aplicar a lógica para lidar com sucessos ou falhas no acompanhamento de inicializações do aplicativo.

Exemplo

[[AppsFlyerTracker sharedTracker] trackAppLaunchWithCompletionHandler:^(NSDictionary<NSString *,id> *dictionary, NSError *error) {
        if (error) {
            NSLog(@"%@", error);
            return;
        }
        if (dictionary) {
            NSLog(@"%@", dictionary);
            return;
        }
        [NSException exceptionWithName:@"fatalError" reason:nil userInfo:nil];
    }];

4. Gravação de eventos in-app

Eventos in-app fornecem insights sobre o que está acontecendo em seu aplicativo. É aconselhável investir tempo para definir os eventos que você deseja avaliar para permitir medir o ROI (retorno sobre o investimento) e LTV (valor de vida útil).

A gravação de eventos in-app é executada chamando trackEvent com parâmetros de nome e valor do evento. Consulte Eventos in-app para obter mais detalhes.

Um nome de evento no aplicativo não deve ultrapassar 45 caracteres. Nomes de eventos com mais de 45 caracteres não aparecem no painel, mas apenas nos Dados brutos e nas APIs de pull e push.

Exemplo: Evento de compra in-app

SwiftObjective-C
AppsFlyerTracker.shared().trackEvent(AFEventPurchase,
  withValues: [
     AFEventParamRevenue: "1200",
     AFEventParamContent: "shoes",
     AFEventParamContentId: "123"
]);

swift-record-in-app-events.png

Isso gera um tipo de evento af_purchase (usando a constante AFEventPurchase) com os seguintes valores de evento: {af_revenue: 200 , af_currency: "USD", af_quantity: 2, af_content_id: "092" af_receipt_id: "9277"} 

 Observação

A AppsFlyer suporta caracteres não pertencentes ao Inglês com eventos no aplicativo, ou com qualquer outra API de SDK, começando da versão 4.8.1 do SDK para iOS.

Para receitas, não adicione símbolos de moedas, pois não são reconhecidos.

 Exemplo de uso

SwiftObjective C
AppsFlyerTracker.shared().trackEvent(AFEventPurchase,
withValues: [
  AFEventParamRevenue: @1200,
  AFEventParamCurrency : @"JPY"
]); 

Verificar a gravação de eventos in-app

Você pode verificar se a gravação de eventos in-app é bem-sucedida ou não, implementando o completionHandler. Depois, você pode aplicar lógica para lidar com o sucesso ou falha de eventos de gravação.

Exemplo

[[AppsFlyerTracker sharedTracker] trackEventWithEventName:AFEventPurchase
	eventValues:@{AFEventParamRevenue: @"1200",
					AFEventParamContent: @"shoes",
					AFEventParamContentId: @"123"}
	completionHandler:^(NSDictionary<NSString *,id> *dictionary, NSError *error) {
	if (error) {
		NSLog(@"%@", error);
		return;
	}
	if (dictionary) {
		NSLog(@"%@", dictionary);
		return;
	}
	[NSException exceptionWithName:@"fatalError" reason:nil userInfo:nil];

5. Realizar deep linking

 Dica

É altamente recomendável ter links diretos integrados em seu aplicativo. O "deep linking" é uma parte crucial nas campanhas de retargeting e é altamente recomendável usá-lo ao executar campanhas desse tipo.

O iOS9 e superior exigem que seu aplicativo ofereça suporte a Links Universais Para mais detalhes, clique aqui.


Para gerenciar links diretos (deep links), adicione o seguinte código em seu aplicativo (na classe delegate do aplicativo). Os métodos deste código permitem que você obtenha dados de links diretos (deep links). Com os dados de links diretos (deep links) você pode redirecionar os usuários para as atividades relevantes do aplicativo e fornecer conteúdos relevantes a eles.

SwiftObjective-C

 func onConversionDataReceived(_ installData: [AnyHashable: Any]) {
  //Handle Conversion Data (Deferred Deep Link)
  }
  
  func onConversionDataRequestFailure(_ error: Error?) {
    //    print("\(error)")
  }
  
  func onAppOpenAttribution(_ attributionData: [AnyHashable: Any]) {
    //Handle Deep Link Data
    
  }
  
  func onAppOpenAttributionFailure(_ error: Error?) {
  }
// Reports app open from a Universal Link for iOS 9 or later
  func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
    AppsFlyerTracker.shared().continue(userActivity, restorationHandler: restorationHandler)
    return true
  }

  // Reports app open from deep link from apps which do not support Universal Links (Twitter) and for iOS8 and below
  func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool {
    AppsFlyerTracker.shared().handleOpen(url, sourceApplication: sourceApplication, withAnnotation: annotation)
    return true
  }

  // Reports app open from deep link for iOS 10 or later
  func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
    AppsFlyerTracker.shared().handleOpen(url, options: options)
    return true
  }
  

 Importante!

Para Swift 4.2 e versões posteriores, use o seguinte código para o método continue userActivity:

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
	AppsFlyerTracker.shared().continue(userActivity, restorationHandler: nil)
	return true
}

6. Gravação de receita

Use o parâmetro de evento af_revenue (AFEventParamRevenue) para contabilizar a receita como parte de um evento in-app. Você pode preenchê-lo com qualquer valor numérico, positivo ou negativo.

 Observação

AFEventParamRevenue (equivalente a usar af_revenue) é o ÚNICO parâmetro de evento que é considerado na AppsFlyer como receita real nos dados brutos e painel. Para mais detalhes, clique aqui.


Exemplo: evento no aplicativo de receita

SwiftObjective-C
AppsFlyerTracker.shared().trackEvent(AFEventPurchase, 
withValues: [
	AFEventParamContentId:"1234567",
	AFEventParamContentType : "category_a",
	AFEventParamRevenue: 1.99,
	AFEventParamCurrency:"USD"
]);

 Importante!

NÃO formate o valor de receita de forma alguma. Ele não deve conter separadores de vírgula, símbolo de moeda ou texto. Um evento de receita deve ser semelhante a 1234.56, por exemplo.

Gravação de receita negativa

Se você precisar registrar receitas negativas, por exemplo, quando um usuário cancela uma compra ou recebe um reembolso, você pode enviar receitas negativas.

SwiftObjective-C
AppsFlyerTracker.shared().trackEvent("cancel_purchase", 
withValues: [
	AFEventParamContentId:"1234567",
	AFEventParamContentType : "category_a",
	AFEventParamRevenue: -1.99,
	AFEventParamCurrency:"USD"
]);

 Observação

Observe o seguinte no código abaixo:

  1. O valor da receita é precedido por um sinal de menos.
  2. O nome do evento tem um valor único de "cancel_purchase" – para permitir que você identifique eventos de receitas negativas no painel e relatórios de dados brutos

7. Obter dados de conversão

A AppsFlyer permite que você acesse os dados de atribuição do usuário em tempo real para cada nova instalação, diretamente do nível do SDK. Isso permite que você personalize conteúdos para os usuários ou os direcione a atividades específicas dentro do aplicativo, o que pode melhorar consideravelmente o engajamento deles em seu aplicativo.

Para mais informações sobre essa funcionalidade avançada, clique aqui.

8. Identificadores de usuários

Há várias opções para recuperar identificadores de usuários:

Obter ID de dispositivo da AppsFlyer

A identificação de dispositivo única da AppsFlyer é criada para cada nova instalação de um aplicativo. É possível obtê-la utilizando o código a seguir:

SwiftObjective-C
let appsflyerId = AppsFlyerTracker.shared().getAppsFlyerUID()

Definir ID de usuário cliente

Definir sua própria identificação de cliente lhe permite fazer uma referência cruzada da sua própria identificação única com a identificação única da AppsFlyer e com as identificações de outros dispositivos. Essa identificação está disponível nos relatórios CSV da AppsFlyer junto com as APIs de postback para referência cruzada com suas identificações internas.

Para definir sua identificação de usuário cliente:

SwiftObjective-C
AppsFlyerTracker.shared().customerUserID = "my user id"

 Observação importante

Recomenda-se definir seu ID de usuário cliente o quanto antes, pois ele é associado apenas a eventos reportados após sua configuração. Se setCustomerUserId for chamado antes de chamar trackAppLaunch, o ID de usuário do cliente está visível na exportação bruta para instalações e para eventos. Se for definido depois, apenas o valor de eventos registrados ficará visível após a chamada deste método.

A identificação do usuário cliente também pode ser usada para concluir integrações com plataformas analíticas como Mixpanel e Swrve.

Obtenção de ID de usuário cliente:

Para obter a ID de usuário cliente, recupere-a do sharedTracker.

[AppsFlyerTracker sharedTracker].customerUserID

 Importante!

Certifique-se de definir a ID de usuário cliente sempre que o aplicativo for inicializado, antes de chamar trackAppLaunch

Para mais informações sobre ID de usuário cliente, clique aqui .

IDFA e IDFV

A AppsFlyer coleta automaticamente o IDFA (identificador para anunciantes) e o IDFV (identificador para fornecedores) se AdSupport.framework estiver incluído no aplicativo.

9. Recursos opcionais

Medir desinstalações

Para a Métrica de desinstalações, ative as notificações remotas por push em seu aplicativo. Consulte o Guia de programação de notificação remota da Apple para obter mais detalhes.

Siga as instruções de integração do SDK do iOS para concluir a configuração do recurso de métrica de desinstalações.

Gravação de Notificações por Push

Para ativar o acompanhamento de inicializações de aplicativos em notificações por push, adicione o código a seguir à delegação do seu aplicativo:

SwiftObjective-C
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any]) {
	AppsFlyerTracker.shared().handlePushNotification(userInfo)
}

A mensagem push deve ter um parâmetro af com os parâmetros de atribuição da AppsFlyer.

Exemplo de mensagem:}

{
  "aps":{
   "alert":"Push text",
   "sound":"default",
   "category":"REMINDER_CATEGORY"
  },
  "_p":123456,
  "payloadKey":"payloadValue",
  "af":{
   "pid":"swrve_int",
   "is_retargeting":"true",
   "c":"test_campaign"
  }
}

Atribuição de promoção cruzada

A AppsFlyer permite que você atribua instalações originadas de uma promoção cruzada de um de seus aplicativos dentro do aplicativo atual do usuário. Aplicativos de promoções cruzadas podem ser um importante fator de crescimento para impulsionar novas instalações para seus aplicativos.

Para obter detalhes, consulte o artigo Atribuição de promoção cruzada aqui.

Atribuição de convite do usuário

A AppsFlyer permite que você atribua e registre instalações originadas de convites do usuário dentro do seu aplicativo. Permitir que os usuários existentes convidem seus amigos e contatos como novos usuários para seu aplicativo pode ser um fator de crescimento importante para seu aplicativo.
 
Para obter detalhes, consulte o artigo Atribuição de convite do usuário aqui.

Definir código de moeda

Você pode definir um código de moeda global usando a API abaixo, além de códigos de moeda específicos que podem ser usados como parte de cada evento no aplicativo enviado para a AppsFlyer. O código de moeda global é usado quando AFEventParamCurrency não é enviado como parte de um evento no aplicativo.

USD é o valor padrão. Você pode encontrar códigos de moeda ISO aceitáveis aqui.

Use a seguinte API para definir o código de moeda:

public void currencyCode(String currencyCode);

Exemplo de uso:

SwiftObjective-C
AppsFlyerTracker.shared().currencyCode = "USD"

Validação de instalações no aplicativo

 Observação

Essa função oferece suporte para o iOS7 e superior.

O SDK da AppsFlyer pode oferecer verificação do servidor de compras no aplicativo. Para configurar o recebimento do acompanhamento de validação, é necessário chamar o método validateAndTrackInAppPurchase dentro do SKStoreKit’s completeTransaction: retorno de chamada. Essa chamada automaticamente gera um evento af_purchase no aplicativo.

- (void) validateAndTrackInAppPurchase:(NSString *) productIdentifier
price:(NSString *) price
currency:(NSString *) currency
transactionId:(NSString *) tranactionId
additionalParameters:(NSDictionary *) params
success:(void (^)(NSDictionary *response)) successBlock
failure:(void (^)(NSError *error, id reponse)) failedBlock;

 Observação

O parâmetro de preço deve conter a receita total associada ao evento de compra validado.


Essa chamada tem dois blocos de callback: um para "sucesso" e outro para "falha" (por qualquer motivo, incluindo falha na validação). Em caso de sucesso, um dicionário é retornado com os dados de validação do recebimento fornecidos pelos servidores da Apple. 

 Importante

Para fins de teste, recomendamos definir o sinalizador useReceiptValidationSandbox para Sim, pois isso redireciona as solicitações para os servidores da área restrita da Apple.

#ifdef DEBUG
[AppsFlyerTracker sharedTracker].useReceiptValidationSandbox = YES;
#endif

 

 Exemplo

Objective-CSwift
[[AppsFlyerTracker sharedTracker] validateAndTrackInAppPurchase:@"ProductIdentifier" price:@"price"
    currency:@"USD"
    transactionId:@"transactionID"
    additionalParameters:@{@"test": @"val" , @"test1" : @"val 1"}
    success:^(NSDictionary *result){
      NSLog(@"Purchase succeeded And verified!!! response: %@", result[@"receipt"]);
    } failure:^(NSError *error, id response) {
      NSLog(@"response = %@", response);
      if([response isKindOfClass:[NSDictionary class]]) {
        if([response[@"status"] isEqualToString:@"in_app_arr_empty"]){
          // retry with 'SKReceiptRefreshRequest' because
          // Apple has returned an empty response
          // <YOUR CODE HERE>
        }

      } else {
        //handle other errors
        return;
      }
  }];

 Importante!

Quando a AppsFlyer valida uma compra contra servidores da Apple, se a resposta contiver uma matriz in-app vazia, a AppsFlyer retorna {"status":"in_app_arr_empty"} para o retorno de chamada de erro.

Se você receber esse sinalizador, deve restaurar o produto adquirido da Apple enviando uma solicitação de atualização de recebimento. Para obter mais informações, consulte a documentação da Apple.

Depois de atualizar o recebimento, chame validateAndTrackInAppPurchase mais uma vez.

Consulte o código acima para saber como lidar com esse erro.

Para uma lista dos possíveis valores de retorno para validação dos recebimentos, consulte a documentação da Apple aqui.

Anonimizar

A AppsFlyer fornece um método para anonimizar identificadores de usuários específicos em suas análises. Esse método está em conformidade com os mais recentes requisitos de privacidade e cumpre as políticas de privacidade e dados do Facebook. O padrão é NÃO, ou seja, a anonimização não está habilitada por padrão.

Use esta API durante a inicialização do SDK para anonimizar explicitamente as instalações, eventos e sessões de um usuário:

SwiftObjective-C
AppsFlyerTracker.shared().deviceTrackingDisabled = true

O acompanhamento pode ser reiniciado ao chamar deviceTrackingDisabled novamente definido como falso.

 Aviso

A anonimização de usuários afeta GRAVEMENTE suas informações de atribuição.
Use essa opção APENAS em regiões que legalmente impedem você de coletar informações de seus usuários.

Personalizar o tempo entre sessões

Por padrão, deve haver um intervalo de, no mínimo, 5 segundos entre duas inicializações de aplicativos para contabilizar como duas sessões separadas (saiba mais sobre contabilização de sessões).

No entanto, é possível usar a seguinte API para definir seu valor personalizado para o tempo mínimo necessário entre sessões:

SwiftObjective-C
AppsFlyerTracker.shared().minTimeBetweenSessions = <your_custom_time_in_seconds>
Observe que definir um alto valor para o tempo personalizado entre inicializações pode gerar um impacto negativo nas APIs que dependem de dados de sessões, como links diretos (deep links).

Sessões em segundo plano para aplicativos utilitários

Indisponível no iOS. 
 

Extensões de aplicativos do iOS e WatchKit

A extensão do aplicativo exige permissões para usar a Internet:

  1. Acesse o arquivo info.plist da extensão do seu aplicativo.
  2. Em NSExtension / NSExtensionAttributes defina o sinalizador RequestsOpenAccess para SIM.

Adicione o código a seguir ao UIViewController viewDidLoad da extensão do aplicativo:

SwiftObjective-C
override func viewDidLoad() {  
    super.viewDidLoad()
    AppsFlyerTracker.shared().appsFlyerDevKey = "MY_APPSFLYER_KEY"

    // MY_APP_ID below stands for you app ID on iTunes Connect. Should be 9 or 10 digits.
    AppsFlyerTracker.shared().appleAppID = "MY_APP_ID"
        
    AppsFlyerTracker.sharedTracker().trackAppLaunch()
  }

Para receber dados de atribuição na extensão do aplicativo, siga as instruções contidas aqui e implemente-as no UIViewController do seu aplicativo em vez do AppDelegate.

Exclusão (opt-out)

Em alguns casos extremos, convém encerrar todas as funções do SDK devido à conformidade legal e de privacidade. Isso pode ser conseguido com a APIisStopTracking. Depois que essa API é invocada, nosso SDK não se comunica mais com nossos servidores e deixa de funcionar.

Há vários cenários diferentes para a exclusão (opt-out) de usuários. É altamente recomendado seguir as instruções exatas do cenário relevante para seu aplicativo.

 Aviso

Use esta API somente quando quiser ignorar totalmente este usuário em toda e qualquer atribuição de instalação e gravação de evento. Usar esta API afeta GRAVEMENTE sua atribuição, coleta de dados e mecanismo de links diretos.

SwiftObjective-C
AppsFlyerTracker.shared().isStopTracking = true

 Importante

Não chame o trackAppLaunch se isStopTracking estiver definido como verdadeiro

Coletar nome do dispositivo

O SDK da AppsFlyer permite que você colete o nome do dispositivo para análise interna. Por padrão, este recurso está desativado. Para ativá-lo, use a seguinte API:

SwiftObjective-C
AppsFlyerTracker.shared().shouldCollectDeviceName = false

 Importante

O nome do dispositivo pode ser considerado um dado pessoal em certas regiões. Colete essa informação somente se estiver legalmente autorizado e tiver recebido o consentimento explícito do usuário para fazê-lo.

Configuração de dados personalizados adicionais

A API setAdditionalData é necessária para integrar-se ao nível do SDK com várias plataformas de parceiros externas, incluindo Segment, Adobe e Urban Airship. Use esta API somente se o artigo de integração da plataforma afirmar especificamente que a API setAdditionalData é necessária.
Veja a seguir um exemplo de código para a implementação do setAdditionalData no iOS para Objective-C ou Swift

Objective-CSwift
NSDictionary* CustomDataMap = [[NSDictionary alloc] initWithObjectsAndKeys:@"value_of_param_1", @"custom_param_1", nil];
  
[[AppsFlyerTracker sharedTracker] setAdditionalData:CustomDataMap];

Corrigindo URLs encurtadas com links diretos (deep links)

Se você estiver usando OneLinks que oferecem suporte a links universais e os envolver com um link universal de terceiros, você pode usar a API setResolveDeepLinkURLs para notificar o SDK da AppsFlyer quais domínios de clique que invocam o aplicativo devem ser resolvidos pelo SDK e ter o OneLink subjacente extraído deles. Isso permitirá que você mantenha um link direto e atribuição enquanto envolve o OneLink com o link universal de um terceiro. Certifique-se de chamar essa API antes da inicialização do SDK.

Objective-CSwift
[AppsFlyerTracker sharedTracker].resolveDeepLinkURLs = @[@"example.com",@"click.example.com"];

10. Testando sua integração

Para mais detalhes sobre como testar sua integração, clique aqui.

Agora você pode começar a medir os resultados das fontes de mídia com as quais você trabalha.

11. Enviar seu aplicativo para a Loja de aplicativos

Você pode encontrar as instruções sobre como enviar seu aplicativo para a Loja de aplicativos aqui.

Esse artigo foi útil?
Usuários que acharam isso útil: 10 de 18

Comentários

0 comentário

Por favor, entrar para comentar.

Conteúdo da Página: