Adtrace 1.1.0

Adtrace 1.1.0

×

由Aref Hosseini和adtrace io维护。

Adtrace 1.1.0

  • 作者：
  • Aref Hosseini

总结

这是 Adtrace™ 的 iOS SDK。您可以在 adtrace.io 上了解更多关于 Adtrace™ 的信息。

如果您的应用程序是一个使用 web view 的应用程序，并且您想从 Javascript 代码中使用 adtrace 跟踪，请参阅我们的 iOS web view SDK 指南。

目录

示例应用

在 examples 目录 中，提供了针对 iOS (Objective-C)、iOS (Swift)、tvOS、iMessage 和 Apple Watch 的示例应用。您可以打开这些 Xcode 项目中的任意一个，了解如何集成 Adtrace SDK。

基本集成

我们将描述将 Adtrace SDK 集成到您的 iOS 项目中的步骤。我们假设您正在使用 Xcode 进行 iOS 开发。

将 SDK 添加到您的项目

如果您正在使用 CocoaPods，请将以下行添加到您的 Podfile 中，然后继续到 此步骤

pod 'Adtrace', '~> 1.1.0'

或者

pod 'Adtrace', :git => 'https://github.com/adtrace/ios_sdk.git', :tag => '1.1.0'

如果您正在使用 Carthage，请将以下行添加到您的 Cartfile 中，然后继续到 此步骤

github "adtrace/ios_sdk"

您还可以选择将 Adtrace SDK 添加到项目作为框架。在 发布页面，您可以找到以下存档：

  • AdtraceSdkStatic.framework.zip
  • AdtraceSdkDynamic.framework.zip
  • AdtraceSdkTv.framework.zip
  • AdtraceSdkIm.framework.zip

自 iOS 8 发布以来，Apple 引入了动态框架（也称为嵌入框架）。如果您的应用目标为 iOS 8 或更高版本，您可以使用 Adtrace SDK 的动态框架。选择您想要使用的框架——静态或动态——并将其添加到您的项目中。

如果您有 tvOS 应用，您可以使用我们的 tvOS 框架以及 Adtrace SDK，该框架可以从 AdtraceSdkTv.framework.zip 存档中提取。

如果您有 iMessage 应用，您也可以使用我们的 IM 框架以及 Adtrace SDK，该框架可以从 AdtraceSdkIm.framework.zip 存档中提取。

添加 iOS 框架

  1. 在“项目导航器”中选择您的项目
  2. 在主视图的左侧，选择您的目标
  3. 在“构建阶段”选项卡中，展开“链接二进制与库”分组
  4. 在此部分的底部，选择 + 按钮
  5. 选择 AdSupport.framework，然后点击 添加 按钮
  6. 除非您使用 tvOS，否则重复以上步骤添加 iAd.framework 和 CoreTelephony.framework
  7. 将框架的 状态 改为 可选。

将 SDK 集成到您的应用程序中

如果您通过 Pod 存储库添加了 Adtrace SDK，应使用以下其中一个导入语句

#import "Adtrace.h"

或者

#import <Adtrace/Adtrace.h>

如果您将 Adtrace SDK 添加为静态/动态框架或通过 Carthage，请使用以下导入语句

#import <AdtraceSdk/Adtrace.h>

如果您在 tvOS 应用程序中使用 Adtrace SDK，请使用以下导入语句

#import <AdtraceSdkTv/Adtrace.h>

如果您在 iMessage 应用程序中使用 Adtrace SDK，请使用以下导入语句

#import <AdtraceSdkIm/Adtrace.h>

接下来，我们将设置基本会话跟踪。

基本设置

在“项目导航器”中打开应用程序代理的源文件。在文件顶部添加 import 语句，然后在应用程序代理的 didFinishLaunching 或 didFinishLaunchingWithOptions 方法中添加以下对 Adtrace 的调用

#import "Adtrace.h"
// or #import <Adtrace/Adtrace.h>
// or #import <AdtraceSdk/Adtrace.h>
// or #import <AdtraceSdkTv/Adtrace.h>
// or #import <AdtraceSdkIm/Adtrace.h>

// ...

NSString *yourAppToken = @"{YourAppToken}";
NSString *environment = ADTEnvironmentSandbox;
ADTConfig *adtraceConfig = [ADTConfig configWithAppToken:yourAppToken
                                            environment:environment];

[Adtrace appDidLaunch:adtraceConfig];

注意：以这种方式初始化 Adtrace SDK 非常重要。否则，您可能会遇到我们在 故障排除部分 中描述的不同类型的问题。

将 {YourAppToken} 替换为您的应用程序令牌。您可以在您的 控制台 中找到它。

根据您是为测试还是为生产构建应用程序，您必须使用以下其中一个值设置 环境。

NSString *environment = ADTEnvironmentSandbox;
NSString *environment = ADTEnvironmentProduction;

重要：如果正在进行测试，或者某人正在测试您的应用程序，则此值应设置为 ADTEnvironmentSandbox。确保在发布应用程序之前将环境设置回 ADTEnvironmentProduction。当您再次开始开发和测试时，将其设置回 ADTEnvironmentSandbox。

我们使用此环境来区分真实流量和测试设备上的测试流量。始终保持此值的关联性非常重要！如果您正在跟踪收入，这一点尤其重要！

针对 iMessage 特定设置

从源码添加SDK：如果您选择从源码将Adtrace SDK添加到您的iMessage应用中，请确保在iMessage项目设置中已设置预处理宏ADTUST_IM=1。

作为框架添加SDK：将AdtraceSdkIm.framework添加到您的iMessage应用后，请确保在项目设置中的构建阶段添加新复制文件阶段，并将AdtraceSdkIm.framework复制到框架文件夹。

会话跟踪：如果您希望在您的iMessage应用中正确实现会话跟踪，您需要进行一个额外的集成步骤。在标准的iOS应用中，Adtrace SDK会自动订阅iOS系统通知，使我们能够知道应用何时进入或离开前台。在iMessage应用的情况下，情况并非如此，因此我们需要您在iMessage应用的视图控制器中添加对trackSubsessionStart和trackSubsessionEnd方法的显式调用，以便使我们的SDK知道应用何时在前台或不在前台。

在didBecomeActiveWithConversation:方法中添加对trackSubsessionStart的调用

-(void)didBecomeActiveWithConversation:(MSConversation *)conversation {
    // Called when the extension is about to move from the inactive to active state.
    // This will happen when the extension is about to present UI.
    // Use this method to configure the extension and restore previously stored state.

    [Adtrace trackSubsessionStart];
}

在willResignActiveWithConversation:方法中添加对trackSubsessionEnd的调用

-(void)willResignActiveWithConversation:(MSConversation *)conversation {
    // Called when the extension is about to move from the active to inactive state.
    // This will happen when the user dissmises the extension, changes to a different
    // conversation or quits Messages.
    
    // Use this method to release shared resources, save user data, invalidate timers,
    // and store enough state information to restore your extension to its current state
    // in case it is terminated later.

    [Adtrace trackSubsessionEnd];
}

设置完成后，Adtrace SDK将能够成功在该iMessage应用中执行会话跟踪。

注意：您应该知道，您的iOS应用以及为它编写的iMessage扩展在不同的内存空间中运行，并且它们还有不同的包标识符。在两个地方使用相同的应用令牌初始化Adtrace SDK将导致两个独立的实例在不互相了解的情况下跟踪事物，这可能会导致您在仪表板数据中看到不希望看到的数据混合。一般的建议是在Adtrace仪表板上为您的iMessage应用创建一个单独的应用，并在其中使用不同的应用令牌初始化SDK。

Adtrace日志记录

通过在您的ADTConfig实例上调用setLogLevel:并使用以下参数之一，您可以增加或减少测试期间看到的日志数量

[adtraceConfig setLogLevel:ADTLogLevelVerbose];  // enable all logging
[adtraceConfig setLogLevel:ADTLogLevelDebug];    // enable more logging
[adtraceConfig setLogLevel:ADTLogLevelInfo];     // the default
[adtraceConfig setLogLevel:ADTLogLevelWarn];     // disable info logging
[adtraceConfig setLogLevel:ADTLogLevelError];    // disable warnings as well
[adtraceConfig setLogLevel:ADTLogLevelAssert];   // disable errors as well
[adtraceConfig setLogLevel:ADTLogLevelSuppress]; // disable all logging

如果您不希望在您的生产应用中显示任何来自Adtrace SDK的日志，则应选择ADTLogLevelSuppress，并且还应使用另一个构造函数初始化ADTConfig对象，在其中启用抑制日志级别模式

#import "Adtrace.h"
// or #import <Adtrace/Adtrace.h>
// or #import <AdtraceSdk/Adtrace.h>
// or #import <AdtraceSdkTv/Adtrace.h>
// or #import <AdtraceSdkIm/Adtrace.h>

// ...

NSString *yourAppToken = @"{YourAppToken}";
NSString *environment = ADTEnvironmentSandbox;
ADTConfig *adtraceConfig = [ADTConfig configWithAppToken:yourAppToken
                                            environment:environment
                                   allowSuppressLogLevel:YES];

[Adtrace appDidLaunch:adtraceConfig];

构建您的应用

构建并运行您的应用。如果构建成功，您应仔细阅读控制台中的SDK日志。在应用首次启动后，您应该看到“安装已跟踪”的信息日志。

附加功能

一旦您将Adtrace SDK集成到您的项目中，您可以利用以下功能。

事件跟踪

您可以使用adtrace来跟踪事件。比如，您想跟踪特定按钮的每一个点击。您需要在您的仪表板中创建一个新的事件令牌，这个令牌关联了一个事件令牌，类似于abc123。然后，在按钮的buttonDown方法中，您会添加以下行来跟踪点击：

ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
[Adtrace trackEvent:event];

点击按钮后，您现在应该在日志中看到事件已跟踪。

事件实例可以在跟踪之前进一步配置事件。

收入跟踪

如果用户可以通过点击广告或在应用内购买来产生收入，您可以使用事件来跟踪这些收入。比如说，一个点击值为一欧元分。然后您可以这样跟踪收入事件：

ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];

[event setRevenue:0.01 currency:@"EUR"];

[Adtrace trackEvent:event];

这当然可以与回调参数结合使用。

当您设置货币令牌时，adtrace将自动将收入转换为所选的报表收入。关于货币转换的更多信息。

您可以在事件跟踪指南中了解更多关于收入和事件跟踪的信息。

收入去重

您还可以传递一个可选的交易ID来避免跟踪重复的收入。最后记住十个交易ID，并跳过具有重复交易ID的收入事件。这对于应用内购买跟踪特别有用。以下是一个示例。

如果您想跟踪应用内购买，请确保只在paymentQueue:updatedTransaction回调中状态更改为SKPaymentTransactionStatePurchased后调用trackEvent。这样，您可以避免跟踪实际上没有产生的收入。

- (void)paymentQueue:(SKPaymentQueue *)queue updatedTransactions:(NSArray *)transactions {
    for (SKPaymentTransaction *transaction in transactions) {
        switch (transaction.transactionState) {
            case SKPaymentTransactionStatePurchased:
                [self finishTransaction:transaction];

                ADTEvent *event = [ADTEvent eventWithEventToken:...];
                [event setRevenue:... currency:...];
                [event setTransactionId:transaction.transactionIdentifier]; // avoid duplicates
                [Adtrace trackEvent:event];

                break;
            // more cases
        }
    }
}

应用内购买验证

如果您想使用Purchase Verification来检查您应用中完成的应用内购买的验证，请检查我们的iOS购买SDK，并了解更多信息这里。

回调参数

您可以在您的仪表板中为事件注册一个回调URL。每当事件被跟踪时，我们将向该URL发送GET请求。您可以在跟踪事件之前通过调用addCallbackParameter向事件添加回调参数。然后，我们将将这些参数附加到您的回调URL。

例如，假设您已注册了URLhttp://www.mydomain.com/callback，然后跟踪以下事件

ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];

[event addCallbackParameter:@"key" value:@"value"];
[event addCallbackParameter:@"foo" value:@"bar"];

[Adtrace trackEvent:event];

在这种情况下，我们将跟踪该事件并向以下URL发送请求

http://www.mydomain.com/callback?key=value&foo=bar

应该注意的是，我们支持各种占位符，如{idfa}，可以用作参数值。在这种情况下，回调中的占位符将被当前设备的广告主ID替换。此外，请注意，我们不会存储任何自定义参数，只附加到回调中，因此如果没有回调，它们将被保存或发送给您。

您可以在我们的回调指南中了解更多关于使用URL回调的信息，包括可用值的完整列表。

合作伙伴参数

您还可以添加需要在Adtrace仪表板中激活的合作伙伴处发送的参数。

这与上面提到的回调参数的工作方式类似，但可以通过在您的ADTEvent实例上调用addPartnerParameter方法来添加。

ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];

[event addPartnerParameter:@"key" value:@"value"];
[event addPartnerParameter:@"foo" value:@"bar"];

[Adtrace trackEvent:event];

您可以在我们的合作伙伴指南中了解更多有关特殊合作伙伴和这些集成的情况。

回调标识符

您还可以为想要跟踪的每个事件添加自定义字符串标识符。该标识符将在后续的事件成功和/或事件失败回调中报告，以便您跟踪哪些事件被成功跟踪或未跟踪。您可以通过在 ADTEvent 实例上调用 setCallbackId 方法来设置此标识符

ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];

[event setCallbackId:@"Your-Custom-Id"];

[Adtrace trackEvent:event];

会话参数

一些参数被保存在每次事件和Adtrace SDK会话中发送。一旦您添加了这些参数之一，您不需要每次都添加它们，因为它们将被保存在本地。如果您添加相同的参数两次，则没有任何效果。

如果您想将会话参数与初始安装事件一起发送，必须在通过 [Adtrace appDidLaunch:] 启动Adtrace SDK之前调用它们。如果您需要在安装时发送它们，但在启动后才能获取所需值，可以延迟Adtrace SDK的首次启动以允许这种行为。

会话回调参数

为事件注册的相同回调参数也可以保存并发送到Adtrace SDK的每个事件或会话。

会话回调参数具有与事件回调参数类似的应用程序接口。不是将键和它的值添加到事件中，而是在调用Adtrace方法的addSessionCallbackParameter:value:时添加。

[Adtrace addSessionCallbackParameter:@"foo" value:@"bar"];

会话回调参数将与添加到事件的回调参数合并。添加到事件的回调参数优先于会话回调参数。这意味着，当向事件添加与从会话添加的相同键的回调参数时，有效的值是添加到事件的回调参数。

可以通过向removeSessionCallbackParameter方法传递所需的键来删除特定的会话回调参数。

[Adtrace removeSessionCallbackParameter:@"foo"];

如果您想从会话回调参数中删除所有键和值，可以使用resetSessionCallbackParameters方法重置它。

[Adtrace resetSessionCallbackParameters];

会话合作伙伴参数

与在Adtrace SDK的每个事件或会话中发送的会话回调参数一样，也存在会话合作伙伴参数。

这些将发送到您的adtrace 仪表板中已激活的集成网络合作伙伴。

会话合作伙伴参数的接口类似于事件合作伙伴参数。不是将键及其值添加到事件中，而是通过调用Adtrace方法addSessionPartnerParameter:value:来添加。

[Adtrace addSessionPartnerParameter:@"foo" value:@"bar"];

会话合作伙伴参数将与添加到事件中的合作伙伴参数合并。添加到事件中的合作伙伴参数优先于会话合作伙伴参数。这意味着，当向事件中添加与从会话添加的具有相同键的合作伙伴参数时，有效的是添加到事件中的合作伙伴参数。

可以通过将期望的键传递到方法removeSessionPartnerParameter中来删除特定的会话合作伙伴参数。

[Adtrace removeSessionPartnerParameter:@"foo"];

如果您希望从会话合作伙伴参数中删除所有键和值，可以使用方法resetSessionPartnerParameters重置。

[Adtrace resetSessionPartnerParameters];

延迟启动

延迟Adtrace SDK的启动可以让您的应用有时间获取会话参数，如唯一标识符，以便在安装时发送。

使用ADTConfig实例中的方法setDelayStart设置初始延迟时间，单位为秒

[adtraceConfig setDelayStart:5.5];

在这种情况下，这将使Adtrace SDK在5.5秒内不发送初始安装会话和创建的任何事件。在这段时间过期或在此期间调用[Adtrace sendFirstPackages]的情况下，每个会话参数都将添加到延迟安装会话和事件中，Adtrace SDK将像往常一样继续。

Adtrace SDK的最大延迟启动时间是10秒.

归因回调

您可以注册一个代理回调来通知跟踪器归因更改。鉴于归因所考虑的不同来源，这些信息不能同步提供。按照以下步骤在.app代理中实现可选的代理协议

请确保考虑我们适用的归因数据策略。点击此处查看相关策略。

  1. 打开 AppDelegate.h 并添加导入语句及 AdtraceDelegate 声明。

    @interface AppDelegate : UIResponder <UIApplicationDelegate, AdtraceDelegate>

  2. 打开 AppDelegate.m 并将以下委托回调函数添加到您的应用委托实现中。

    - (void)adtraceAttributionChanged:(ADTAttribution *)attribution {
}

  3. 使用您的 ADTConfig 实例设置委托

    [adtraceConfig setDelegate:self];

由于委托回调是通过 ADTConfig 实例配置的，因此在调用 [Adtrace appDidLaunch:adtraceConfig] 之前，您应先调用 setDelegate。

在 SDK 收到最终的归因数据后，将调用委托函数。在委托函数中，您可以访问 attribution 参数。以下是它的属性快速摘要

  • NSString trackerToken 当前归因的跟踪器令牌。
  • NSString trackerName 当前归因的跟踪器名称。
  • NSString network 当前列为归因的网路分组级别。
  • NSString campaign 当前列为归因的活动分组级别。
  • NSString adgroup 当前列为归因的广告分组级别。
  • NSString creative 当前列为归因的创意分组级别。
  • NSString clickLabel 当前列为归因的点击标签。
  • NSString adid 归因提供的唯一设备标识符。

如果任何值不可用，它将默认为 nil。

广告收入跟踪

您可以通过以下方法调用 Adtrace SDK 来跟踪广告收入信息。

[Adtrace trackAdRevenue:source payload:payload];

您需要传递的该方参数是

  • source - 标识广告收入信息来源的 NSString 对象。
  • payload - 包含广告收入 JSON 的 NSData 对象。

目前我们支持的 source 参数值如下

  • ADTAdRevenueSourceMopub - 代表 MoPub 中介平台（更多信息，请查看 集成指南）

事件和会话回调

您可以登记一个委托回调，以通知成功和失败的跟踪事件和/或会话。用于 归因回调 的相同可选协议 AdtraceDelegate 也可用于此处。

按照相同的步骤，并为成功追踪的事件实现以下委托回调函数

- (void)adtraceEventTrackingSucceeded:(ADTEventSuccess *)eventSuccessResponseData {
}

以下为失败追踪事件的委托回调函数

- (void)adtraceEventTrackingFailed:(ADTEventFailure *)eventFailureResponseData {
}

对于成功追踪的会话

- (void)adtraceSessionTrackingSucceeded:(ADTSessionSuccess *)sessionSuccessResponseData {
}

以及失败追踪的会话

- (void)adtraceSessionTrackingFailed:(ADTSessionFailure *)sessionFailureResponseData {
}

当SDK尝试向服务器发送数据包后，将调用代理函数。在代理回调中，您可以访问为代理回调特有的响应数据对象。以下是会话响应数据属性的简要概述

  • NSString message 服务器发送的消息或SDK记录的错误。
  • NSString timeStamp 服务器的时间戳。
  • NSString adid adtrace提供的唯一设备标识符。
  • NSDictionary jsonResponse 服务器响应的JSON对象。

两个事件响应数据对象都包含

  • NSString eventToken 如果跟踪的数据包是事件，则为事件令牌。
  • NSString callbackId 在事件对象上设置的自定义定义的回调ID。

如果任何值不可用，它将默认为 nil。

事件和会话失败对象还包含

  • BOOL willRetry 表示将在稍后尝试重新发送数据包。

禁用跟踪

您可以通过调用带有参数NO的setEnabled来禁用Adtrace SDK对当前设备上任何活动的跟踪。**该设置会在会话之间保留**。

[Adtrace setEnabled:NO];

您可以通过调用函数isEnabled来检查Adtrace SDK目前是否处于启用状态。您始终可以通过调用带有启用参数为YES的setEnabled来激活Adtrace SDK。

离线模式

您可以将Adtrace SDK设置为离线模式，暂停向我们的服务器发送数据，同时保留调的数据以稍后发送。在离线模式下，所有信息都保存在文件中，因此请在离线模式下小心不要触发太多事件。

您可以通过调用带有参数YES的setOfflineMode来激活离线模式。

[Adtrace setOfflineMode:YES];

相反，您可以通过调用带有参数NO的setOfflineMode来取消离线模式。当Adtrace SDK重新回到在线模式时，所有保存的信息都将带有时戳发送到我们的服务器。

与禁用跟踪不同，此设置**不在会话之间保留**。这意味着每次启动时，SDK都处于在线模式，即使应用在离线模式下终止也是如此。

事件缓冲

如果您的应用程序大量使用事件跟踪，您可能希望将一些HTTP请求批量发送，每分钟发送一次。您可以通过您的ADTConfig实例启用事件缓冲。

[adtraceConfig setEventBufferingEnabled:YES];

如果没有设置，事件缓冲默认是禁用的。

GDPR的权利被遗忘

根据欧盟通用数据保护条例（GDPR）第17条，当用户行使他们权利被遗忘时，您可以通知Adtrace。调用以下方法将指示Adtrace SDK将用户选择遗忘的通知发送到Adtrace后端

[Adtrace gdprForgetMe];

收到此信息后，Adtrace将删除用户数据，Adtrace SDK将停止跟踪用户。未来不会从此设备发送请求到Adtrace。

SDK签名

Adtrace SDK签名是在每个客户端的基础上启用的。如果您对使用此功能感兴趣，请联系您的账户经理。

如果您账户上已启用SDK签名，并且您有权访问Adtrace仪表板中的App密钥，请使用以下方法将SDK签名集成到您的应用程序中。

通过在您的AdtraceConfig实例上调用setAppSecret设置App密钥。

[adtraceConfig setAppSecret:secretId info1:info1 info2:info2 info3:info3 info4:info4];

后台跟踪

Adtrace SDK的默认行为是在应用程序处于后台时暂停发送HTTP请求。您可以在AdtraceConfig实例中更改此设置。

[adtraceConfig setSendInBackground:YES];

如果没有设置，后台发送默认是禁用的。

设备ID

Adtrace SDK为您提供获取设备标识符的可能性。

苹果设备广告识别符

某些服务（例如 Google Analytics）要求您协调设备和客户端标识符，以防止重复报告。

要获取设备标识符 IDFA，调用 idfa 函数

NSString *idfa = [Adtrace idfa];

Adtrace 设备标识符

对于安装了您应用的所有设备，Adtrace 后台生成唯一的 Adtrace 设备标识符（adid）。为了获取此标识符，您可以在 Adtrace 实例上调用以下方法

NSString *adid = [Adtrace adid];

注意：关于 adid 的信息将在应用安装被 Adtrace 后台跟踪后可用。从那时起，Adtrace SDK 将有关设备 adid 的信息，您可以使用此方法访问它。因此，在 SDK 初始化完成并且应用安装跟踪成功之前，**无法**访问 adid。

用户归因

归因回调将触发，如归因回调部分所述，提供有关任何新归因的信息，每当它发生变化时。在其他情况下，如果您想访问有关您当前用户归因的信息，您可以调用 Adtrace 实例的以下方法

ADTAttribution *attribution = [Adtrace attribution];

注意：有关当前归因的信息将在应用安装已被 Adtrace 后台跟踪并且首次触发归因回调后可用。从那时起，Adtrace SDK 将有关您用户归因的信息，您可以使用此方法访问它。因此，在 SDK 初始化完成并且归因回调被首次触发之前，**无法**访问用户的归因值。

推送令牌

推送令牌用于 Audience Builder 和客户端回调，并且它们对于卸载和重新安装跟踪是必需的。

要将推送通知令牌发送给我们，请在您的应用代理中didRegisterForRemoteNotificationsWithDeviceToken方法中添加以下调用到 Adtrace

- (void)application:(UIApplication *)app didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [Adtrace setDeviceToken:deviceToken];
}

预装跟踪器

如果您想使用Adtrace SDK来识别已在设备上预装了您的应用的用户，请按照以下步骤操作。

  1. 在您的仪表板中创建一个新的跟踪器。
  2. 打开您的应用代理并设置ADTConfig的默认跟踪器
ADTConfig *adtraceConfig = [ADTConfig configWithAppToken:yourAppToken environment:environment];
[adtraceConfig setDefaultTracker:@"{TrackerToken}"];
[Adtrace appDidLaunch:adtraceConfig];

将{TrackerToken}替换为在步骤2中创建的跟踪器令牌。请注意，仪表板显示跟踪器URL（包括http://app.adtrace.io/）。在您的源代码中，您应指定仅包含六个字符的令牌，而不是整个URL。

  1. 构建并运行您的应用。您应该在XCode中看到如下类似行

    Default tracker: 'abc123'

深度链接

如果您在使用带有深度链接选项的adtrace跟踪器URL，则有可能获取深度链接URL及其内容的信息。当用户已经安装了您的应用时（标准深度链接场景）或他们设备上没有应用（延迟深度链接场景）时，都会触发URL。这两种场景都由Adtrace SDK支持，并且在这两种情况下，深度链接URL将在您的应用启动后击中跟踪器URL后提供给您。为了在您的应用中使用此功能，您需要正确设置。

标准深度链接场景

如果您的用户已经安装了应用，并带有深度链接信息的跟踪器URL，则应用将被打开，深度链接的内容将发送到您的应用，以便您解析并决定下一步要做什么。随着iOS 9的引入，苹果改变了在应用中处理深度链接的方式。根据您希望为您的应用使用的场景（或者如果您希望同时使用它们以支持广泛范围的设备），您需要设置您的应用来处理以下两种场景之一或两个。

旧版iOS equipment中的深度链接

旧版iOS 8及以下版本的设备使用自定义URL方案设置来完成深度链接。您需要选择一个自定义URL方案名称，您的应用程序将负责打开该方案。此方案名称还将作为deep_link参数的一部分用于adtrace追踪器URL。为了在您的应用程序中设置此参数，打开您的Info.plist文件，并在其中添加新的URL types行。在那里，作为URL identifier，写入您应用程序的Bundle ID，然后在URL schemes下添加您想要您的应用程序处理的选择方案名称。在下面的示例中，我们选择了我们的应用程序应该处理adtraceExample方案名称。

设置完成后，当您点击带有deep_link参数的adtrace追踪器URL时，应用程序将打开。打开应用程序后，您的AppDelegate类中的openURL方法将被触发，并且从追踪器URL中传递的deep_link参数的其中位置将交付。如果想要访问深度链接的内容，请覆盖此方法。

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
  sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    // url object contains your deep link content

    // Apply your logic to determine the return value of this method
    return YES;
    // or
    // return NO;
}

通过此设置，您已成功为iOS 8和更早版本的iOS设备设置深度链接处理。

旧版iOS 9及更高版本中的深度链接

为了设置旧版iOS 9及更高版本设备的深度链接支持，您需要启用您的应用程序以便处理苹果通用链接。有关通用链接的详细信息以及它们的设置方法，您可以在此处查找。

Adtrace正在幕后处理与通用链接相关的许多事情。但是，为了使用Adtrace支持通用链接，您需要在adtrace仪表板上进行小型的通用链接设置。有关应执行的操作的更多详细信息，请参阅我们的官方文档。

在成功启用仪表板中的通用链接功能后，您还需要在您的应用程序中进行以下操作

在Apple Developer Portal中为您的应用程序启用Associated Domains后，您需要在您的应用程序的Xcode项目中执行相同操作。启用Assciated Domains后，将adtrace仪表板中为您生成的通用链接添加到Domains部分，用applinks:前缀进行标记，并确保删除通用链接中的http(s)部分。

设置完成后，点击广告追踪器通用链接后，您的应用将被打开。打开应用后，您的AppDelegate类中的continueUserActivity方法将被触发，并将通用链接URL的内容发送到指定的位置。如果您想访问深链内容，请重写此方法。

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity
 restorationHandler:(void (^)(NSArray *restorableObjects))restorationHandler {
    if ([[userActivity activityType] isEqualToString:NSUserActivityTypeBrowsingWeb]) {
        NSURL *url = [userActivity webpageURL];

        // url object contains your universal link content
    }

    // Apply your logic to determine the return value of this method
    return YES;
    // or
    // return NO;
}

使用此设置，您已成功为iOS 9及其以上版本的iOS设备设置了深链处理。

我们提供了一个辅助函数，可以将通用链接转换为旧式深链接URL，以防您的代码中存在一些旨在接收旧式自定义URL方案格式的深链信息的自定义逻辑。您可以使用通用链接和您希望将深链前缀的自定义URL方案名称调用此方法，我们将为您生成自定义URL方案的深链接。

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity
 restorationHandler:(void (^)(NSArray *restorableObjects))restorationHandler {
    if ([[userActivity activityType] isEqualToString:NSUserActivityTypeBrowsingWeb]) {
        NSURL *url = [userActivity webpageURL];

        NSURL *oldStyleDeeplink = [Adtrace convertUniversalLink:url scheme:@"adtraceExample"];
    }

    // Apply your logic to determine the return value of this method
    return YES;
    // or
    // return NO;
}

延迟深链接场景

您可以在延迟深链接打开前注册一个代理回调，以便在Adtrace SDK尝试打开它之前得到通知并决定是否打开。用于归属回调和事件和会话回调的同一名义协议AdtraceDelegate用于此处。

按照相同的步骤，并实现以下委托回调函数以处理延迟深链接

- (BOOL)adtraceDeeplinkResponse:(NSURL *)deeplink {
    // deeplink object contains information about deferred deep link content

    // Apply your logic to determine whether the Adtrace SDK should try to open the deep link
    return YES;
    // or
    // return NO;
}

回调函数将在SDK从我们的服务器收到延迟深链接并打开之前被调用。在回调函数内，您有权访问深链。返回的布尔值决定了SDK是否将启动深链接。例如，您可以暂时不允许SDK打开深链接，将其保存并在稍后自行打开。

如果不实现此回调，默认情况下，Adtrace SDK将始终尝试打开深链接。

通过深链接进行重新归属

Adtrace允许您使用深链接运行重新 Engagement 活动。有关如何进行的更多信息，请查看我们的官方文档。

如果您使用此功能，为了确保您的用户得到适当的重新归属，您需要在您的应用中对Adtrace SDK进行一次额外的调用。

一旦您在您的应用中收到深链接内容信息，请调用appWillOpenUrl方法。通过此调用，Adtrace SDK将尝试查找深链接中是否存在任何新的归属信息，如果有，它将发送到Adtrace后端。如果您用户应因为点击包含深链内容的Adtrace追踪器URL而重新归属，您将在您的应用中看到带有此用户的新归属信息的attribution callback被触发。

调用appWillOpenUrl的方法如下，以为所有iOS版本配置深链接重新归属

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
  sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    // url object contains your deep link content
    
    [Adtrace appWillOpenUrl:url];

    // Apply your logic to determine the return value of this method
    return YES;
    // or
    // return NO;
}
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity
 restorationHandler:(void (^)(NSArray *restorableObjects))restorationHandler {
    if ([[userActivity activityType] isEqualToString:NSUserActivityTypeBrowsingWeb]) {
        NSURL url = [userActivity webpageURL];

        [Adtrace appWillOpenUrl:url];
    }

    // Apply your logic to determine the return value of this method
    return YES;
    // or
    // return NO;
}

故障排除

延迟初始化 SDK 的相关问题

如《基本设置步骤》所述，我们强烈建议你在你的应用程序代理的 didFinishLaunching 或 didFinishLaunchingWithOptions 方法中初始化 Adtrace SDK。尽快初始化 Adtrace SDK 是非常重要的，这样你才能使用 SDK 的所有功能。

未能立即初始化 Adtrace SDK 可能会对你的应用程序中的跟踪产生各种影响：为了在应用程序中执行任何类型的跟踪，Adtrace SDK 必须 被初始化。

如果你决定在进行 SDK 初始化之前执行以下操作

它们将不会执行。

如果你想在 SDK 真正初始化之前使用 Adtrace SDK 跟踪以下行为，你必须在应用程序内部构建一个 自定义行为队列机制。你需要排队所有你想让我们的 SDK 执行的操作，然后将它们在 SDK 初始化后执行。

离线模式状态不会改变，跟踪启用/禁用状态不会改变，深度链接重新赋值将无法发生，所有被跟踪的事件都将被 丢弃。

延迟 SDK 初始化可能会影响会话跟踪。在 Adtrace SDK 实际初始化前，它无法收集任何会话长度信息。这可能会影响仪表板上的 DAU 数据，可能无法得到正确跟踪。

让我们举一个例子：假设这个场景：当你加载某些特定的视图或视图控制器时初始化 Adtrace SDK，假设这既不是启动画面也不是你的应用程序的第一个屏幕，而是用户从主屏幕导航到该屏幕。如果用户下载你的应用程序并打开它，主屏幕将会显示。在这个时候，这个用户已经完成安装，应该被追踪。然而，Adtrace SDK 对此一无所知，因为用户需要导航到之前提到的屏幕，在那里你决定初始化 Adtrace SDK。进一步来说，如果用户决定他/她不喜欢这个应用程序并在看到主屏幕后立即卸载它，上述所有信息将不会被我们的 SDK 跟踪，也不会在仪表板上显示。

事件跟踪

对于您想要跟踪的事件，使用某种内部队列机制排队，并在SDK初始化后进行跟踪。在初始化SDK之前跟踪事件会导致事件被丢弃并永久丢失，因此请确保在SDK初始化并启用后跟踪它们。

离线模式与启用/禁用跟踪

离线模式不是在SDK初始化之间持久化的功能，因此它默认设置为false。如果您在初始化SDK之前尝试启用离线模式，当最终初始化SDK时，它仍然设置为false。

启用/禁用跟踪是SDK初始化之间持久化的设置。如果您在初始化SDK之前尝试切换此值，则切换尝试将被忽略。一旦初始化，SDK将处于（启用或禁用）的状态，就像在切换尝试之前一样。

通过深链接重置归因

如上述所述，在处理深链接重置归因时，根据您使用的深度链接机制（旧式与通用链接），您将获得NSURL对象，然后需要执行以下调用

[Adtrace appWillOpenUrl:url]

如果您在SDK初始化之前执行此调用，来自深链接URL的归因信息将永久丢失。如果要让Adtrace SDK成功重置您的用户，您需要将这些NSURL对象信息排队，并在SDK初始化后触发appWillOpenUrl方法。

会话跟踪

会话跟踪是Adtrace SDK自动执行的功能，超出了应用开发者的能力范围。为了正确进行会话跟踪，必须按照本README文件建议初始化Adtrace SDK。不这样做可能会对会话跟踪和仪表板中的DAU数字产生不可预知的影响。

例如

  • 一个用户打开并删除了您的应用，而SDK甚至未初始化，导致安装和会话从未被跟踪，因此从未在仪表板中报告。
  • 如果用户在午夜之前下载并打开您的应用，而Adtrace SDK在午夜之后初始化，所有排队的安装和会话数据将报告在错误的日子。
  • 如果用户在某个日子里没有使用您的应用，但在午夜后不久打开它，SDK在午夜后初始化，导致DAU在另一天报告，而不是在应用开启的那天。

由于所有这些原因，请遵循本文件中的说明，在您的应用代理的didFinishLaunching或didFinishLaunchingWithOptions方法中初始化Adtrace SDK。

我看到了“Adtrace requires ARC”错误

如果您的构建失败并显示错误Adtrace requires ARC，则表明您的项目未使用ARC。在这种情况下，我们建议将项目迁移到ARC。如果您不想使用ARC，您必须在目标的“构建阶段”中为adtrace的所有源文件启用ARC。

展开“编译源文件”组，选择所有adtrace文件，并将“编译器标志”更改为-fobjc-arc（选择所有并按Return键一次性更改全部）。

我看到了“[UIDevice adtTrackingEnabled]: unrecognized selector sent to instance”错误

此错误可能在添加Adtrace SDK框架到您的应用时出现。Adtrace SDK在其源文件中包含categories，因此如果您选择了这种SDK集成方法，则需要在Xcode项目设置中的“其他链接器标志”中添加-ObjC标志。添加此标志将修复此错误。

我看到了“Session failed (Ignoring too frequent session.)”错误

此错误通常发生在测试安装时。卸载并重新安装应用并不足以触发新的安装。服务器将确定SDK已经丢失了本地聚集的会话数据，并忽略错误消息，因为根据服务器上设备的信息。

在测试过程中，这种行为可能很繁琐，但这是为了尽可能让沙盒行为与生产环境匹配

您可以在我们的服务器上重置设备的会话数据。检查日志中的错误消息

Session failed (Ignoring too frequent session. Last session: YYYY-MM-DDTHH:mm:ss, this session: YYYY-MM-DDTHH:mm:ss, interval: XXs, min interval: 20m) (app_token: {yourAppToken}, adid: {adidValue})

在下面填写{yourAppToken}以及{adidValue}或{idfaValue}之后，打开以下链接之一

http://app.adtrace.io/forget_device?app_token={yourAppToken}&adid={adidValue}

http://app.adtrace.io/forget_device?app_token={yourAppToken}&idfa={idfaValue}

当设备被遗忘时，链接只返回“忘记设备”。如果设备已经被遗忘或值不正确，链接返回“找不到设备”。

日志中未看到“安装已跟踪”

如果您想在测试设备上模拟应用安装场景，仅仅从测试设备上的Xcode重新运行应用是不够的。从Xcode重新运行应用不会导致应用数据被清除，我们SDK在应用内部保留的所有内部文件仍然存在，因此再次运行时，我们的SDK将看到那些文件，认为您的应用已经安装（并且SDK已经启动）但只是再次打开而不是首次打开。

为了运行应用安装场景，您需要执行以下操作

  • 从您的设备中卸载应用（完全删除它）
  • 按照上述问题中的说明，从adtrace后端忘记您的测试设备
  • 从测试设备上的Xcode运行您的应用，您将看到日志消息“安装已跟踪”

我看到了“无法归因的SDK点击被忽略”的消息

您可能在测试应用时的沙盒环境中看到这条消息。这与苹果在iAd.framework的3.0版本中引入的一些更改有关。因此，用户可以从点击iAd横幅被引导到您的应用，这将导致我们的SDK向adtrace后端发送一个sdk_click包，通知其关于被点击URL的内容。出于某种原因，苹果决定如果应用在没有点击iAd横幅的情况下打开，他们将人工生成一个带有随机值的iAd横幅URL点击。我们的SDK无法区分iAd横幅点击是真实的还是人工生成的，并将发送一个sdk_click包到adtrace后端。如果您将日志级别设置为verbose，您将看到这个sdk_click包的样子类似如下

[Adtrace]d: Added package 1 (click)
[Adtrace]v: Path:      /sdk_click
[Adtrace]v: ClientSdk: ios4.10.1
[Adtrace]v: Parameters:
[Adtrace]v:      app_token              {YourAppToken}
[Adtrace]v:      created_at             2016-04-15T14:25:51.676Z+0200
[Adtrace]v:      details                {"Version3.1":{"iad-lineitem-id":"1234567890","iad-org-name":"OrgName","iad-creative-name":"CreativeName","iad-click-date":"2016-04-15T12:25:51Z","iad-campaign-id":"1234567890","iad-attribution":"true","iad-lineitem-name":"LineName","iad-creative-id":"1234567890","iad-campaign-name":"CampaignName","iad-conversion-date":"2016-04-15T12:25:51Z"}}
[Adtrace]v:      environment            sandbox
[Adtrace]v:      idfa                   XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
[Adtrace]v:      idfv                   YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY
[Adtrace]v:      needs_response_details 1
[Adtrace]v:      source                 iad3

如果由于某种原因这个sdk_click被接受，这意味着通过点击其他活动URL打开您的应用的用户或even作为有机用户，将被错误地归因到这个不存在的iAd源。这就是为什么我们的后端忽略它，并使用这条消息通知您的原因

[Adtrace]v: Response: {"message":"Unattributable SDK click ignored."}
[Adtrace]i: Unattributable SDK click ignored.

因此，这条消息并不表示您的SDK集成有任何问题，而是在向您告知，我们的后端已经忽略了可能造成用户被错误地归因/重新归因的人工创建的sdk_click。

我在adtrace仪表板中看到不正确的收入数据

Adtrace SDK追踪您要求其追踪的内容。如果您将收入附加到事件中，则您写入作为金额的数字是唯一将到达adtrace后端并在仪表板中显示的金额。我们的SDK不会操纵您的金额值，也不会操纵我们的后端。所以，如果您看到被跟踪的金额不正确，那是因为我们的SDK被告诉跟踪该金额。

通常，跟踪收入事件的用户代码看起来像这样

// ...

- (double)someLogicForGettingRevenueAmount {
    // This method somehow handles how user determines
    // what's the revenue value which should be tracked.

    // It is maybe making some calculations to determine it.

    // Or maybe extracting the info from In-App purchase which
    // was successfully finished.

    // Or maybe returns some predefined double value.

    double amount; // double amount = some double value

    return amount;
}

// ...

- (void)someRandomMethodInTheApp {
    double amount = [self someLogicForGettingRevenueAmount];

    ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
    [event setRevenue:amount currency:@"EUR"];
    [Adtrace trackEvent:event];
}

如果仪表板中显示的任何值不是您期望跟踪的，请查看确定金额值逻辑。