Adtrace-sdk 在 CocoaPods.org

概述

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

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

示例应用程序

在 examples 目录内有适用于 iOS (Objective-C)、iOS (Swift)、tvOS、iMessage 和 Apple Watch 的示例应用程序。您可以打开这些任何 Xcode 项目以查看如何将 Adtrace SDK 集成到示例中。

基本集成

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

将 SDK 添加到您的项目中

如果您正在使用 CocoaPods，您可以将以下行添加到您的 Podfile 中并从此步骤继续操作

pod 'Adtrace-sdk', '~> 2.3.0'

或

pod 'Adtrace-sdk', :git => 'https://github.com/adtrace/adtrace_sdk_iOS', :tag => 'v2.3.0'

如果您正在使用 Carthage，您可以将以下行添加到您的 Cartfile 中并从此步骤继续操作

github "adtrace/adtrace_sdk_iOS"

集成 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 非常重要。否则，您可能会遇到我们在故障排除部分中描述的不同类型的问题。

用 {您的AppToken} 代替您的应用令牌。您可以在您的仪表板中找到它。

根据您是为测试还是为生产构建应用程序，您必须使用以下值之一设置 environment

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

重要：如果正在测试您的应用程序，则应将此值设置为 ADTEnvironmentSandbox。只有在这种情况下，您才应该在发布应用程序之前将其设置为 ADTEnvironmentProduction。当您开始再次开发并测试时，将其设置回 ADTEnvironmentSandbox。

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

iMessage 特殊设置

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

作为框架添加 SDK：在将 AdtraceSdkIm.framework 添加到您的 iMessage 应用之后，请确保在您的 Build Phases 项目设置中添加 New Copy Files Phase 并选择将 AdtraceSdkIm.framework 复制到 Frameworks 文件夹。

会话跟踪：如果您希望在您的 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 扩展运行在不同的内存空间中，并且它们有自己的包标识符。在两个地方使用相同的 app 令牌初始化 Adtrace SDK 将导致两个独立的实例跟踪事物，而且它们之间互不知情，这可能导致您在仪表板数据中不想看到的数据混合。一般建议为您的 iMessage 应用在 Adtrace 仪表板中创建单独的应用，并在其中初始化 SDK，使用不同的 app 令牌。

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集成到您的项目中，您就可以利用以下功能。

AppTrackingTransparency框架

对于发送的每个包，Adtrace后端将收到以下四种（4）状态之一，用于访问可用于跟踪用户或设备的相关数据

已授权
拒绝
未确定
限制

在设备收到用于用户设备跟踪的相关数据访问授权请求以供批准后，返回的状态将是已授权或拒绝。

在设备收到用于跟踪用户或设备的相关数据访问授权请求之前，返回的状态将是未确定。

如果使用应用程序跟踪数据授权受到限制，则返回的状态将是限制。

SDK具有内置机制，在用户响应弹出对话框后接收更新后的状态，以防您不想自定义您显示的弹出对话框。为了方便有效地将新的同意状态传达给后端，Adtrace SDK提供了一种包装器，该包装器如以下章节所述的App-tracking authorization wrapper中所述的app跟踪授权方法。SDK将使用您的回调方法将状态传达给后端，以方便地高效将新的同意状态传达给后端。

App-tracking授权包装器

Adtrace SDK提供了一种可能性，可用于请求用户授权访问他们的应用程序相关数据。Adtrace SDK基于requestTrackingAuthorizationWithCompletionHandler:方法提供了一个包装器，您还可以定义回调方法以获取有关用户选择的更多信息。通过使用此包装器，一旦用户响应对话框，就会通过您的回调方法传达。SDK还将通知后端用户的选择。通过您的回调方法传递的NSUInteger值具有以下含义

0: ATTrackingManagerAuthorizationStatusNotDetermined
1: ATTrackingManagerAuthorizationStatusRestricted
2: ATTrackingManagerAuthorizationStatusDenied
3: ATTrackingManagerAuthorizationStatusAuthorized

要使用此包装器，您可以调用如下所示

[Adtrace requestTrackingAuthorizationWithCompletionHandler:^(NSUInteger status) {
    switch (status) {
        case 0:
            // ATTrackingManagerAuthorizationStatusNotDetermined case
            break;
        case 1:
            // ATTrackingManagerAuthorizationStatusRestricted case
            break;
        case 2:
            // ATTrackingManagerAuthorizationStatusDenied case
            break;
        case 3:
            // ATTrackingManagerAuthorizationStatusAuthorized case
            break;
    }
}];

获取当前授权状态

要获取当前的app跟踪授权状态，您可以调用[Adtrace appTrackingAuthorizationStatus]，这将返回以下可能性之一

0: 用户尚未被询问
1: 用户设备受限制
2: 用户拒绝访问IDFA
3: 用户授权访问IDFA
-1: 状态不可用

SKAdNetwork框架

如果您已实施Adtrace iOS SDK v2.0.5或更高版本，并且您的应用程序正在运行iOS 14，那么与SKAdNetwork的通信会默认开启，尽管您可以选择将其关闭。开启后，Adtrace在初始化SDK时会自动注册SKAdNetwork属性归属。如果事件在Adtrace仪表板上设置以接收转换值，Adtrace后端会将转换值数据发送到SDK。然后SDK设置转换值。一旦Adtrace收到SKAdNetwork回调数据，就会将它显示在仪表板上。

如果您希望Adtrace SDK不自动与SKAdNetwork通信，您可以通过在配置对象上调用以下方法来禁用此功能。

[adtraceConfig deactivateSKAdNetworkHandling];

更新SKAdNetwork转换值

从iOS SDK v2.0.5版本开始，您可以使用Adtrace SDK包装方法updateConversionValue:来更新用户的SKAdNetwork转换值。

[Adtrace updateConversionValue:6];

转换值更新回调

您可以通过注册回调在每个Adtrace SDK更新用户转换值时接收通知。您需要实现AdtraceDelegate协议，实现可选的adtraceConversionValueUpdated:方法

- (void)adtraceConversionValueUpdated:(NSNumber *)conversionValue {
    NSLog(@"Conversion value updated callback called!");
    NSLog(@"Conversion value: %@", conversionValue);
}

事件跟踪

您可以使用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:updatedTransactions中调用finishTransaction之后，只有在状态变为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
        }
    }
}

回调参数

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

例如，假设您已注册URL http://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实例上的addEventValueParameter方法进行添加。

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

[event addEventValueParameter:@"key" value:@"value"];
[event addEventValueParameter:@"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 delegate中实现可选的代理协议

请确保考虑我们的适用的归因数据策略。

打开 AppDelegate.h 并添加导入和 AdtraceDelegate 声明。

@interface AppDelegate : UIResponder <UIApplicationDelegate, AdtraceDelegate>

打开 AppDelegate.m 并将以下代理回调函数添加到您的app delegate 实现中。
```
- (void)adtraceAttributionChanged:(ADTAttribution *)attribution {
}
```
使用您的 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 由归因提供的唯一设备标识符。
NSString costType 成本类型字符串。
NSNumber costAmount 成本金额。
NSString costCurrency 成本货币字符串。

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

注意：成本数据（ costType，costAmount & costCurrency）仅当通过调用 setNeedsCost: 方法在 ADTConfig 中配置时可用。如果没有配置或配置但不是归因的一部分，这些字段将具有值 nil。此功能在SDK v2.0.5及以上版本可用。

事件和会话回调

您可以注册一个代理回调来通知成功和失败的跟踪事件和/或会话。用于归因回调的相同可选协议 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 到离线模式，暂停向我们的服务器传输数据，同时保留将来的跟踪数据。在离线模式下，所有信息都保存在文件中，因此请注意在离线模式下不要触发太多事件。

您可以通过调用 setOfflineMode 并传入参数 YES 来激活离线模式。

[Adtrace setOfflineMode:YES];

相反，您可以通过调用 setOfflineMode 并传入 NO 来禁用离线模式。当 Adtrace SDK 切换回在线模式时，所有保存的信息都将带有正确的时间信息发送到我们的服务器。

与禁用跟踪不同，此设置 不会在会话之间保存。这意味着 SDK 在启动时总是处于在线模式，即使应用在离线模式下被终止。

事件缓冲

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

[adtraceConfig setEventBufferingEnabled:YES];

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

SDK 签名

Adtrace SDK 签名是根据客户端分别启用的。如果您对使用此功能感兴趣，请联系您的账户经理。

如果您的帐户上已经启用了 SDK 签名并且您可以访问 Adtrace 控制台中的 App Secrets，请使用以下方法将 SDK 签名集成到您的应用中。

通过在您的 AdtraceConfig 实例上调用 setAppSecret 来设置 App Secret

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

后台跟踪

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

[adtraceConfig setSendInBackground:YES];

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

设备 ID

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

iOS 广告识别符

某些服务（如 Google Analytics）需要您协调设备和客户端 ID 以避免重复报告。

要获取设备标识符 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 SDK 就有了关于用户归因的信息，您可以通过此方法访问它。因此，在SDK初始化和归因回调用初始触发之前，无法访问用户归因的值。

推送令牌

推送令牌用于受众构建和客户端回调，并且对于卸载和重新安装跟踪是必需的。

为了发送推送通知令牌，请将以下调用添加到您的应用程序代理的didRegisterForRemoteNotificationsWithDeviceToken中。

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

深度链接

如果您在adtrace追踪器URL中使用带深度链接选项的URL deep link到您的应用程序，则有可能获取有关深度链接URL及其内容的详细信息。用户可能会点击URL，这发生在用户已经安装了您的应用程序的情况下（标准深度链接场景）或者如果他们设备上没有应用程序（延迟深度链接场景）。这两种场景都由Adtrace SDK支持，在两种情况下，深度链接URL将在用户启动应用程序后在触及追踪器URL后为您提供。为了在应用中使用此功能，您需要正确地进行配置。

标准深度链接场景

如果您的用户已经安装了应用程序，并且使用带有深度链接信息的追踪器URL点击，则会打开您的应用程序，并将深度链接的内容发送到您的应用程序，以便您可以解析并决定下一步操作。随着iOS 9的推出，苹果更改了在应用中处理深度链接的方式。根据您希望为您的应用程序使用哪个场景（或者您希望同时使用它们以支持广泛的设备），您需要设置您的应用程序以处理以下一个或两个场景。

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

为了为iOS 9及更高版本设备设置深度链接支持，您需要启用应用程序以处理苹果通用链接。有关通用链接及其设置的更多信息，您可以检查这里。

Adtrace在幕后负责处理与通用链接相关的许多事情。但是，为了与Adtrace一起支持通用链接，您需要在小范围链接仪表板中进行一些设置。有关应该做什么的更多信息，请参阅我们的官方文档。

一旦您在仪表板中成功启用了通用链接功能，您还需要在应用程序中执行以下操作。

在Apple开发者门户为您的应用程序启用关联域名后，您需要在应用程序的Xcode项目中执行同样操作。在启用关联域名后，请将Adtrace仪表板中为您生成的通用链接添加到域名部分，并在其前缀为applinks:，并确保您也从通用链接中删除了http(s)部分。

完成此设置后，您点击adtrace追踪通用链接后，应用将被打开。应用打开后，您的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默认总是尝试打开深度链接。

故障排除

延迟SDK初始化的问题

如基本设置步骤中所述，我们强烈建议您在应用代理的didFinishLaunching或didFinishLaunchingWithOptions方法中初始化Adtrace SDK。尽快初始化Adtrace SDK是至关重要的，这样您就可以使用SDK的所有功能。

如果您决定不立即初始化Adtrace SDK，可能会对应用中的跟踪造成各种影响：为了执行应用中的任何形式的跟踪，Adtrace 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 将处于之前切换尝试的状态（启用或禁用）。

通过深度链接进行再归因

如上文所述，当处理深度链接重定向时，根据你使用的深度链接机制（旧样式 vs. 全局链接），你将获取 NSURL 对象，然后需要执行以下调用

[Adtrace appWillOpenUrl:url]

如果你在 SDK 未初始化之前执行此调用，来自深度链接 URL 的归因信息将永远丢失。如果你想使 Adtrace SDK 成功重新归因你的用户，你需要排队此 NSURL 对象信息，并在 SDK 初始化后触发 appWillOpenUrl 方法。

会话跟踪

会话跟踪是 Adtrace SDK 自动执行的操作，是应用开发者无法触及的。为了正确地进行会话跟踪，关键是按照本 README 中的建议初始化 Adtrace SDK。如果不这样做，可能会对会话跟踪的正确性和仪表板中的 DAU 数目产生不可预测的影响。

例如

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

出于所有这些原因，请按照本文件中的说明初始化 Adtrace SDK，并在你的应用代理的 didFinishLaunching 或 didFinishLaunchingWithOptions 方法中执行。

我看到了 "Adtrace requires ARC" 错误

如果您在构建时遇到 Adtrace requires ARC 的错误，这表明您的项目没有使用 ARC。在这种情况下，我们建议您将项目移植所以它会使用 ARC。如果您不想使用 ARC，您需要在目标的构建阶段中为 adtrace 的所有源文件启用 ARC。

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

我在看到 "[UIDevice adtTrackingEnabled]: unrecognized selector sent to instance" 错误。

当您将 Adtrace SDK 框架添加到您的应用程序时，可能会发生此错误。Adtrace SDK 包含其源文件中的 类别。因此，如果您选择了此 SDK 集成方法，您需要将 -ObjC 标志添加到 Xcode 项目的 其他链接器标志 中。添加此标志将修复此错误。

我看到了 "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.com/forget_device?app_token={yourAppToken}&adid={adidValue}

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

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

我没有在日志中看到 " Install tracked"。

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

为了运行应用程序安装场景，您需要进行以下操作：

从您的设备上卸载应用程序（完全删除它）
从 adtrace 后端忘记您的测试设备，如上所述
在测试设备上的 Xcode 中运行您的应用程序，您会看到日志消息 "Install tracked"

我看到 "不可追溯的 SDK 点击被忽略" 消息

当您在 沙盒 环境中测试应用程序时，您可能会注意到这条消息。它与苹果在 iAd.framework 版本 3 中引入的一些变化有关。在这种情况下，用户可以从 iAd 標签点击中指向您的应用程序，这将导致我们的 SDK 向 adtrace 后端发送一个包含有关单击 URL 内容的 sdk_click 包。由于某些原因，苹果决定如果应用程序在不点击 iAd 横幅的情况下打开，他们会人工生成包含一些随机值的 iAd 横幅 URL 点击。我们的 SDK 无法区分 iAd 横幅点击是真实的还是人工生成的，并将向 adtrace 后端发送一个 sdk_click 包。如果您的记录级别设置为 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打开您应用程序的用户，甚至是有机用户，都将被分配到这个不存在的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];
}

如果在仪表板上看到除您期望跟踪之外的其他任何值，请检查您确定金额值的逻辑。

许可

Adtrace SDK依据MIT许可证授权。

在此，任何人免费获得本软件及其相关文档（“软件”）的副本，并有权在无损条件下处理软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或转售软件副本，并允许向软件提供的人这样做，前提是符合以下条件

本软件按照“现状”提供给用户，不提供任何形式的保证，无论是明示的还是隐含的，包括但不限于适销性、适用于特定目的和无侵权性。在任何情况下，作者或版权持有者不对因本软件或其使用或其他方式而产生的任何索赔、损害或其他责任负责。

Adtrace-sdk 2.3.0

Adtrace-sdk 2.3.0

Adtrace-sdk 2.3.0

概述

目录

示例应用程序

基本集成

将 SDK 添加到您的项目中

集成 SDK 到您的应用程序

基本设置

iMessage 特殊设置

Adtrace 日志记录

构建应用程序

其他特性

AppTrackingTransparency框架

App-tracking授权包装器

获取当前授权状态

SKAdNetwork框架

更新SKAdNetwork转换值

转换值更新回调

事件跟踪

收入跟踪

收入去重

回调参数

值参数

回调标识符

会话参数

会话回调参数

会话合作伙伴参数

延迟启动

归因回调

事件和会话回调

禁用跟踪

离线模式

事件缓冲

SDK 签名

后台跟踪

设备 ID

iOS 广告识别符

Adtrace 设备标识符

用户归因

推送令牌

深度链接

标准深度链接场景

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

延迟深度链接场景

故障排除

延迟SDK初始化的问题

事件跟踪

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

通过深度链接进行再归因

会话跟踪

我看到了 "Adtrace requires ARC" 错误

我在看到 "[UIDevice adtTrackingEnabled]: unrecognized selector sent to instance" 错误。

我看到了 "Session failed (Ignoring too frequent session.)" 错误。

我没有在日志中看到 " Install tracked"。

我看到 "不可追溯的 SDK 点击被忽略" 消息

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

许可