SDK Version: 4.8.11(Release notes)
1. Visão geral
Este guia fornece detalhes sobre como integrar o SDK da AppsFlyer em seu aplicativo do iOS. Você pode acompanhar instalações, atualizações, sessões e eventos adicionais no aplicativo, além de instalações de aplicativos (incluindo compras no aplicativo, níveis de jogos, etc.) para avaliar o ROI e os níveis de engajamento do usuário. O SDK do iOS é compatível com todos os dispositivos iOS (iPhone, iPod, iPad) com a versão 6 do iOS e as mais recentes.
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
- Chapters 2 and 3 are MANDATORY to implement BASIC SDK integration, i.e. install attribution only
- Tracking in-app events chapter is HIGHLY RECOMMENDED to implement
- The rest of the described features are OPTIONAL to implement, although some of them may be necessary for you, depending on your app's business logic. For example, tracking 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
- Certifique-se de ter baixado e instalado a versão mais recente do CocoaPods.
- Adicione a linha a seguir ao seu
Podfile
:pod 'AppsFlyerFramework'
- execute o
pod install
- Certifique-se de usar o arquivo
.xcworkspace
para abrir seu projeto no Xcode, em vez do arquivo.xcodeproj
, daqui em diante.
- Certifique-se de ter instalado a última versão do Carthage.
- Adicione a linha a seguir no Cartfile:
- binário "https://raw.githubusercontent.com/AppsFlyerSDK/AppsFlyerFramework/master/AppsFlyerTracker.json"
Observação
Esse método é compatível apenas com o iOS 8 e superior.
- Faça download do SDK para iOS como um framework estático
Para verificar a integridade do download do framework estático do SDK, clique aqui. - Descompacte o arquivo AppsFlyerLib.framework.zip que acabou de baixar.
- Arraste o AppsFlyerLib.framework e solte em seu projeto do Xcode.
- Certifique-se de que Copiar itens se necessário está selecionado
- Adicione o AdSupport.framework e o iAd.framework ao seu projeto e configure como Opcional
Observação
- Essa abordagem é recomendada apenas se você deseja oferecer suporte ao iOS 7 em seu aplicativo.
- When importing the Static Lib into a Swift project the
AppsFlyerTracker.h
file must be added as a bridging header to your project.
- Faça download do SDK para iOS como uma biblioteca estática
Para verificar a integridade do download da biblioteca estática do SDK, clique aqui. - Descompacte o arquivo que você baixou.
- Arraste e solte o AppsFlyerTracker.h e o libAppsFlyerLib.a em seu projeto Xcode.
- Certifique-se de que Copiar itens se necessário está selecionado
- Adicione o AdSupport.framework e o iAd.framework ao seu projeto e configure como Opcional
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 acompanhar os anúncios do Facebook, Twitter, Google e outras redes. - iAd.framework
- Essa estrutura é necessária para acompanhar os Anúncios do Apple Search em seu aplicativo.
2.2 Configurar integração no App Delegate
Abra seu arquivo AppDelegate.m do aplicativo e importe o SDK da AppsFlyer:
importe a AppsFlyerLib
#import <AppsFlyerLib/AppsFlyerTracker.h>
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".
AppsFlyerTracker.shared().appsFlyerDevKey = "<your-appsflyer-dev-key>";
AppsFlyerTracker.shared().appleAppID = "123456789"
AppsFlyerTracker.shared().delegate = self
#ifdef 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
:
func applicationDidBecomeActive(application: UIApplication) {
// Track Installs, updates & sessions(app opens) (You must include this API to enable tracking)
AppsFlyerTracker.shared().trackAppLaunch()
// your other code here.... }
- (void)applicationDidBecomeActive:(UIApplication *)application {
// Track Installs, updates & sessions(app opens) (You must include this API to enable tracking)
[[AppsFlyerTracker sharedTracker] trackAppLaunch];
// your other code here.... }
4. Acompanhamento de eventos no aplicativo
Os eventos no aplicativo fornecem insights sobre o que está acontecendo em seu aplicativo. É aconselhável investir tempo para definir os eventos que deseja avaliar para permitir que o acompanhamento do ROI (Retorno sobre o investimento) e do LTV (Valor de vida útil).
O acompanhamento de eventos in-app é realizado chamando trackEvent
com o nome do evento e os parâmetros de valor. 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.
Example: Purchase In-App Event
AppsFlyerTracker.shared().trackEvent(AFEventPurchase,
withValues: [
AFEventParamRevenue: "1200",
AFEventParamContent: "shoes",
AFEventParamContentId: "123"
]);
This generates an af_purchase
event type (using the AFEventPurchase
constant) with the following event values: {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.
Não adicione qualquer símbolo de moeda ou pontos decimais aos números, pois os mesmos não são reconhecidos
Exemplo de uso
AppsFlyerTracker.shared().trackEvent(AFEventPurchase,
withValues: [
AFEventParamRevenue: @1200,
AFEventParamCurrency : @"JPY"
]);
[[AppsFlyerTracker sharedTracker] trackEvent: AFEventPurchase
withValues: @{
AFEventParamRevenue: @1200, AFEventParamCurrency: @"JPY"
}];
5. Acompanhamento de links diretos
Dica
É altamente recomendável habilitar o suporte a "deep linking" 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 relatar essas inicializações, adicione o código a seguir à delegação do seu aplicativo:
// 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
}
// Reports app open from a Universal Link for iOS 9 or above
- (BOOL) application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray *_Nullable))restorationHandler {
[[AppsFlyerTracker sharedTracker] continueUserActivity:userActivity restorationHandler:restorationHandler];
return YES;
}
// Reports app open from deep link from apps which do not support Universal Links (Twitter) and for iOS8 and below
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString*)sourceApplication annotation:(id)annotation {
[[AppsFlyerTracker sharedTracker] handleOpenURL:url sourceApplication:sourceApplication withAnnotation:annotation];
return YES;
}
// Reports app open from deep link for iOS 10
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
options:(NSDictionary *) options {
[[AppsFlyerTracker sharedTracker] handleOpenUrl:url options:options];
return YES;
}
6. Acompanhamento de receitas
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
AppsFlyerTracker.shared().trackEvent(AFEventPurchase,
withValues: [
AFEventParamContentId:"1234567",
AFEventParamContentType : "category_a",
AFEventParamRevenue: 1.99,
AFEventParamCurrency:"USD"
]);
[[AppsFlyerTracker sharedTracker] trackEvent: AFEventPurchase
withValues:@{
AFEventParamContentId:@"1234567",
AFEventParamContentType : @"category_a",
AFEventParamRevenue: @1.99,
AFEventParamCurrency:@"USD"
}];
Importante!
Do NOT format the revenue value in any way. It should not contain comma separators, currency sign, or text. A revenue event should be similar to 1234.56, for example.
7. Obter dados de conversão
A AppsFlyer permite que você acesse os dados de atribuição de usuário em tempo real para cada nova instalação, diretamente do nível do SDK. Assim, você pode personalizar conteúdos para os usuários ou os direcionar para atividades específicas dentro do aplicativo, o que pode aumentar 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:
let appsflyerId = AppsFlyerTracker.shared().getAppsFlyerUID()
NSString *appsflyerId = [AppsFlyerTracker sharedTracker].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:
AppsFlyerTracker.shared().customerUserID = "my user id"
[AppsFlyerTracker sharedTracker].customerUserID = @"my user id";
Observação importante
It is recommended to set your Customer User ID
as soon as possible as it is only associated to events reported after its setup. If setCustomerUserId
is called before calling trackAppLaunch
, the Customer User ID is visible in the raw export for installs and for events. If it is set after, only the value for events tracked is visible after calling this method.
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:
To get the customer user ID retrieve it from the sharedTracker.
[AppsFlyerTracker sharedTracker].customerUserID
Importante!
Make sure to set the customer user ID each time the app is launched, before calling trackAppLaunch</code.
Para mais informações sobre ID de usuário cliente, clique aqui .
Definir o e-mail do usuário
A AppsFlyer lhe permite informar um ou mais endereços de e-mail de usuários se você os coletar em seu aplicativo. Os valores de e-mail podem ser criptografados seguindo os métodos de criptografia: Sha1, MD5 e simples.
Exemplo: coleta de e-mail do usuário
AppsFlyerTracker.shared().setUserEmails( ["email1@domain.com", "email2@domain.com"],
with: EmailCryptTypeSHA1)
[[AppsFlyerTracker sharedTracker] setUserEmails:@[@"email1@domain.com", @"email2@domain.com"]
withCryptType:EmailCryptTypeSHA1];
Observação
Informações de identificação pessoal (PII), como endereços de e-mail, não são retidas pela AppsFlyer, nem são apresentadas em relatórios. O objetivo da coleta dessas informações é apenas para propósitos de postback às fontes de mídia.
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
Measure Uninstalls
For Uninstall measurement, enable remote push notification on your app. See Apple's Remote Notification Programming Guide for more details.
Follow the iOS SDK integration instructions to complete the uninstall measurement feature setup.
Acompanhamento das 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:
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any]) {
AppsFlyerTracker.shared().handlePushNotification(userInfo)
}
-(void) application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
[[AppsFlyerTracker sharedTracker] handlePushNotification:userInfo];
}
A mensagem por push deve ter um parâmetro af
com os parâmetros de acompanhamento 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"
}
}
Acompanhamento de promoções cruzadas
A AppsFlyer permite que você acompanhe e 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 mais detalhes, consulte o artigo Acompanhamento de promoções cruzadas aqui.
Acompanhamento de convites de usuários
Definir código de moeda
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:
AppsFlyerTracker.shared().currencyCode = "USD"
[AppsFlyerTracker sharedTracker].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 acompanhamento de validação de recebimento, é 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
[[AppsFlyerTracker sharedTracker] validateAndTrackInAppPurchase:product.productIdentifier price:product.price.stringValue
currency:@"USD"
transactionId:trans.transactionIdentifier
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);
}];
AppsFlyerTracker.shared().validateAndTrack(inAppPurchase: product.productIdentifier, price: "\(product.price)", currency: product.priceLocale.currencyCode, transactionId: trans.transactionIdentifier, additionalParameters: nil,success:{(result) in
print("Purchase succeeded And verified!!! response \(result)")
},failure:{(error,message) in
print("response = \(message)")
})
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 requisitos de privacidade mais recentes 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:
AppsFlyerTracker.shared().deviceTrackingDisabled = true
[AppsFlyerTracker sharedTracker].deviceTrackingDisabled = YES;
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:
AppsFlyerTracker.shared().minTimeBetweenSessions = <your_custom_time_in_seconds>
[AppsFlyerTracker sharedTracker].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.
Sessões em segundo plano para aplicativos utilitários
Extensões de aplicativos do iOS e WatchKit
A extensão do aplicativo exige permissões para usar a Internet:
- Acesse o arquivo info.plist da extensão do seu aplicativo.
- Em
NSExtension
/NSExtensionAttributes
defina o sinalizadorRequestsOpenAccess
para SIM.
Adicione o código a seguir ao UIViewController viewDidLoad
da extensão do aplicativo:
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()
}
- (void)viewDidLoad {
[super viewDidLoad];
// Replace MY_APPSFLYER_KEY below by your AppsFlyer dev key
[AppsFlyerTracker sharedTracker].appsFlyerDevKey = @"MY_APPSFLYER_KEY";
// MY_APP_ID below stands for you app ID on iTunes Connect. Should be 9 or 10 digits.
[AppsFlyerTracker sharedTracker].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)
In some extreme cases you might want to shut down all SDK tracking due to legal and privacy compliance. This can be achieved with the isStopTracking API. Once this API is invoked, our SDK no longer communicates with our servers and stops functioning.
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 this API only in cases where you want to fully ignore this user from any and all tracking. Using this API SEVERELY impacts your attribution, data collection and deep linking mechanism.
AppsFlyerTracker.shared().isStopTracking = true
[AppsFlyerTracker sharedTracker].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:
>AppsFlyerTracker.shared().shouldCollectDeviceName = false`
[AppsFlyerTracker sharedTracker].shouldCollectDeviceName = NO;
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 APIsetAdditionalData é necessária para integrar-se ao nível do SDK com várias plataformas 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
NSDictionary* CustomDataMap = [[NSDictionary alloc] initWithObjectsAndKeys:@"value_of_param_1", @"custom_param_1", nil];
[[AppsFlyerTracker sharedTracker] setAdditionalData:CustomDataMap];
let CustomDataMap: [AnyHashable: Any] = [
"custom_param_1" : "value_of_param_1"
]
AppsFlyerTracker.shared().customData = CustomDataMap
10. Testando sua integração
Para mais detalhes sobre como testar sua integração, clique aqui.
Now you can start tracking the media sources you work with.
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.
Comentários
Por favor, entrar para comentar.