SDK v5 迁移指南

操作前须知

在更新到 SDK v5 之前，您需要进行以下操作：

SDK v5 支持SDK 签名验证。如果您正在使用 SDK 签名库，请先从应用中移除签名库。
SDK v5 支持的最低 API 版本已更新。如果您的应用目标版本较低，请先进行更新。
- iOS: 12.0
- 安卓： 21

安装 SDK

要开始使用 SDK v5，您需要将其添加为项目的依赖。为此，请将下列依赖添加至您的pubspec.yaml文件：

dependencies:
adjust_sdk: ^5.0.0

变更

安装 v5 SDK 后，您需要更新现有的 Adjust 代码以使用新的 API。

初始化方法

在 SDK v4 中，初始化方法为Adjust.start 。在 SDK v5 中，该方法已变为Adjust.initSdk 。

Adjust.start(adjustConfig); // v4
Adjust.initSdk(adjustConfig); // v5

配置

本节介绍 SDK 配置变更。

禁用或启用 SDK

在 SDK v4 中，您可以通过调用带bool值的Adjust.setEnabled来启用和禁用 SDK。

Adjust.setEnabled(false); // disable SDK
Adjust.setEnabled(true); // enable SDK

在 SDK v5 中，为清晰起见，此功能被分成单独的命令。

调用Adjust.disable来禁用 SDK。
调用Adjust.enable来启用 SDK。

Adjust.disable();
Adjust.enable();

在后台发送信息

在 SDK v4 中，您可以将adjustConfig实例上的sendInBackground属性设置为true，以此允许 SDK 在应用后台运行时向 Adjust 发送信息。

adjustConfig.sendInBackground = true;

在 SDK v5 中，您需要将adjustConfig实例上的isSendingInBackgroundEnabled属性设置为true，以此允许 SDK 在应用后台运行时向 Adjust 发送信息。

adjustConfig.isSendingInBackgroundEnabled = true;

预安装应用监测

在 SDK v4 中，您可以将adjustConfig实例的preinstallTrackingEnabled属性设置为true来监测预安装应用。

adjustConfig.preinstallTrackingEnabled = true;

在 SDK v5 中，您需要将adjustConfig实例的isPreinstallTrackingEnabled属性设置为true来启用预安装应用监测。

adjustConfig.isPreinstallTrackingEnabled = true;

禁用 AdServices 信息读取

在 SDK v4 中，您可以将adjustConfig实例的allowAdServicesInfoReading属性设置为false，以防止 Adjust SDK 读取 AdServices 信息。

adjustConfig.allowAdServicesInfoReading = false;

在 SDK v5 中，您需要将adjustConfig实例的isAdServicesEnabled属性设置为false，以防止 Adjust SDK 读取 AdServices 信息。

adjustConfig.isAdServicesEnabled = false;

禁用 IDFA 读取

在 SDK v4 中，您可以将adjustConfig实例的allowIdfaReading属性设置为false，以防止 Adjust SDK 读取设备的 IDFA。

adjustConfig.allowIdfaReading = false;

在 SDK v5 中，您需要将adjustConfig实例的isIdfaReadingEnabled属性设置为false，以防止 Adjust SDK 读取设备的 IDFA。

adjustConfig.isIdfaReadingEnabled = false;

在归因中启用成本数据

在 SDK v4 中，您可以将adjustConfig实例的needsCost属性设置为true，在设备的归因信息中包含成本数据。

adjustConfig.needsCost = true;

在 SDK v5 中，您需要将adjustConfig实例的isCostDataInAttributionEnabled属性设置为true，才能在设备的归因信息中包含成本数据。

adjustConfig.isCostDataInAttributionEnabled = true;

启用 LinkMe

在 SDK v4 中，您可以将adjustConfig实例的linkMeEnabled属性设置为true，启用 LinkMe。

adjustConfig.linkMeEnabled = true;

在 SDK v5 中，您需要将adjustConfig实例的isLinkMeEnabled属性设置为true，才能启用 Adjust LinkMe。

adjustConfig.isLinkMeEnabled = true;

只读取设备 ID 一次

在 SDK v4 中，您可以将adjustConfig实例的readDeviceInfoOnceEnabled属性设置为true，以指示 SDK 只读取设备 ID 一次。

adjustConfig.readDeviceInfoOnceEnabled = true;

在 SDK v5 中，您需要将adjustConfig实例的isDeviceIdsReadingOnceEnabled属性设置为true，以指示 SDK 只读取设备 ID 一次。

adjustConfig.isDeviceIdsReadingOnceEnabled = true;

离线模式

在 SDK v4 中，您可以通过调用带bool参数的Adjust.setOfflineMode来启用和禁用 SDK 离线模式。

Adjust.setOfflineMode(true);
Adjust.setOfflineMode(false);

在 SDK v5 中，为清晰起见，此功能被分成单独的命令。

调用Adjust.switchToOfflineMode将 SDK 设为离线模式。
调用Adjust.switchBackToOnlineMode将 SDK 重新设为在线模式。

Adjust.switchToOfflineMode(); // Put the SDK in offline mode
Adjust.switchBackToOnlineMode(); // Put the SDK back in online mode

事件缓冲

SDK v4 支持事件缓冲。该功能可将请求事件、广告收入、推送标签 (Push token) 和其他信息存储在本地缓冲区中以便在之后发送。

adjustConfig.eventBufferingEnabled = true;

SDK v5 中已删除该设置。

自定义用户代理字符串

SDK v4 支持通过向 adjustConfig 实例上的 userAgent 属性指定用户字符串代理来设置自定义用户代理。

adjustConfig.userAgent = 'custom-user-agent';

SDK v5 中已删除该设置。

设置设备是否已知

在 SDK v4 中，您可以将adjustConfig实例的isDeviceKnown属性，手动告知 SDK 设备是否为已知设备。

adjustConfig.isDeviceKnown = true;

SDK v5 中已删除该设置。

延迟 SDK 启动

SDK v4 支持通过将adjustConfig实例的delayStart属性设置为延迟来延迟 SDK 启动。您最多可以设置 10 秒 的延迟。

adjustConfig.delayStart = 10;

此设置已在 SDK v5 中删除，包括Adjust.checkForNewAttStatus方法。调用该方法会使 SDK 停止延迟，继续工作。

最终安卓归因

在 SDK v4 中，您可以将adjustConfig实例的finalAndroidAttributionEnabled属性设置为true来提供最终安卓归因。

adjustConfig.finalAndroidAttributionEnabled = true;

在 SDK v5 中，该设置已被移除，因为安卓平台上只有最终归因会通过归因回传发送。

AdjustEvent 变更

在 SDK v4 中，您可以将receipt 发送到adjustEvent.receipt 上的adjustEvent 属性以进行订阅和购买监测。

adjustEvent.receipt = 'receipt';

SDK v5 中已移除该类属性，因为该类属性已不再用于收入验证。

记录功能

本节介绍向 Adjust 发送信息的功能变更。

会话回传参数

在 SDK v4 中，您可以通过传递键值对至Adjust.addSessionCallbackParameter方法来添加会话参数，也可以使用Adjust.removeSessionCallbackParameter方法移除单个参数。

Adjust.addSessionCallbackParameter('key', 'value');
Adjust.removeSessionCallbackParameter('key');
Adjust.resetSessionCallbackParameters();

在 SDK v5 中，会话参数被重命名为统一参数。

Adjust.addGlobalCallbackParameter('key', 'value');
Adjust.removeGlobalCallbackParameter('key');
Adjust.removeGlobalCallbackParameters();

会话合作伙伴参数

在 SDK v4 中，您可以通过传递键值对至Adjust.addSessionPartnerParameter方法来添加会话合作伙伴参数，也可以使用Adjust.removeSessionPartnerParameter方法移除单个参数。

Adjust.addSessionPartnerParameter('key', 'value');
Adjust.removeSessionPartnerParameter('key');
Adjust.resetSessionPartnerParameters();

在 SDK v5 中，会话合作伙伴参数被重命名为统一合作伙伴参数。

Adjust.addGlobalPartnerParameter('key', 'value');
Adjust.removeGlobalPartnerParameter('key');
Adjust.removeGlobalPartnerParameters();

发送订阅信息

本节介绍 Adjust SDK 中订阅发送的变更。

App Store 订阅

在 SDK v4 中，您可以通过配置AdjustAppStoreSubscription对象来设置新的订阅。该对象使用四个参数进行初始化：price 、 currency 、 transactionId和receipt 。

AdjustAppStoreSubscription subscription = new AdjustAppStoreSubscription(
   price,
   currency,
   transactionId,
   receipt);

在SDK v5 中，您无需发送receipt参数，因为收入验证不再需要此参数。

AdjustAppStoreSubscription subscription = new AdjustAppStoreSubscription(
   price,
   currency,
   transactionId);

App Store 购买

在 SDK v4 中，您可以通过配置AdjustAppStorePurchase对象来设置新的购买。该对象使用三个参数进行初始化：receipt 、 product ID和transaction ID 。

AdjustAppStorePurchase purchase = new AdjustAppStorePurchase(receipt, productId, transactionId);

在SDK v5 中，您无需发送receipt参数，因为收入验证不再需要此参数。

AdjustAppStorePurchase purchase = new AdjustAppStorePurchase(productId, transactionId);

Play 商店订阅

在 SDK v4 中，您可以通过向setPurchaseTime方法传递时间戳来记录用户购买订阅的日期。

adjustPlayStoreSubscription.setPurchaseTime('purchase-time');

在 SDK v5 中，您需要为adjustPlayStoreSubscription实例的purchaseTime属性指定时间戳以记录用户购买订阅的日期。

adjustPlayStoreSubscription.purchaseTime = 'purchase-time';

深度链接

本节介绍 Adjust SDK 中深度链接的变更。

通过深度链接进行再归因

在 SDK v4 中，您可以将深度链接信息传递至Adjust.appWillOpenUrl方法。

Adjust.appWillOpenUrl('url');

为清晰起见，在 SDK v5 中，该方法已重命名为Adjust.processDeeplink 。其中添加了新的AdjustDeeplink类用于构建深度链接。要处理深度链接，请使用您的深度链接 URL 实例化AdjustDeeplink对象并将其传递至Adjust.processDeeplink方法。

Adjust.processDeeplink(new AdjustDeeplink('url'));

启动延迟深度链接

在 SDK v4 中，您可以将adjustConfig实例的launchDeferredDeeplink属性设置为true，使 SDK 打开深度链接。

adjustConfig.launchDeferredDeeplink = true;

在 SDK v5 中，您需要将adjustConfig实例的isDeferredDeeplinkOpeningEnabled属性设置为true，SDK 才能打开深度链接。

adjustConfig.isDeferredDeeplinkOpeningEnabled = true;

深度链接解析

在 SDK v4 中，您可以通过将url传递至processDeeplink方法来解析缩短的深度链接。

Adjust.processDeeplink('url').then((resolvedLink) {
    // resolvedLink is the unshortened link
};

在 SDK v5 中，您需要发送使用深度链接url初始化的AdjustDeeplink对象。此操作会返回未缩短的原始深度链接。

Adjust.processAndResolveDeeplink(new AdjustDeeplink('url')).then((resolvedLink) {
    // resolvedLink is the unshortened link
};

隐私功能

本节介绍 Adjust SDK 隐私功能的变更。

《儿童在线隐私权保护法》(COPPA) 合规

在 SDK v4 中，您可以将adjustConfig实例的coppaCompliantEnabled属性设置为true，启用 COPPA 合规。

adjustConfig.coppaCompliantEnabled = true;

在 SDK v5 中，您需要将adjustConfig实例的isCoppaComplianceEnabled属性设置为true，启用 COPPA 合规。

adjustConfig.isCoppaComplianceEnabled = true;

Play Store 儿童应用

在 SDK v4 中，您可以将adjustConfig 实例的playStoreKidsAppEnabled属性设置为true，将应用标记为Play 商店儿童应用。该属性会在 SDK 初始化期间读取，也就是说 SDK 初始化后该值将无法更新。

adjustConfig.playStoreKidsAppEnabled = true;

在 SDK v5 中，您需要将adjustConfig实例的isPlayStoreKidsComplianceEnabled属性设置为true，才能启用合规。

adjustConfig.isPlayStoreKidsComplianceEnabled = true;

设置数据驻留和 URL 策略

在 SDK v4 中，URL 策略和数据驻留域名在adjustConfig类中被定义为常量。

adjustConfig.setUrlStrategy(AdjustConfig.DataResidencyEU);

在 SDK v5 中，您需要将选定的一个或多个域名以数组的形式发送。您还需要进行下列设置：

useSubdomains (bool): 域名是否应被视为 Adjust 域名。若为 true，则 SDK 会为域名添加 Adjust 子域名前缀。若为 false，SDK 会使用收到的域名，不添加任何前缀。
isDataResidency ( bool )：域名是否用于数据驻留。

adjustConfig.setUrlStrategy(['eu.adjust.com'], true, true);

请查看下方表格，了解如何在 SDK v5 中配置 URL 策略。

v4	v5 - 主要和后备域名	v5 - 使用子域名	v5 - 数据驻留
`adjustConfig.DataResidencyEU`	`'eu.adjust.com'`	`true`	`true`
`adjustConfig.DataResidencyTR`	`'tr.adjust.com'`	`true`	`true`
`adjustConfig.DataResidencyUS`	`'us.adjust.com'`	`true`	`true`
`adjustConfig.UrlStrategyChina`	`'adjust.world'`： `'adjust.com'`	`true`	`false`
`adjustConfig.UrlStrategyCn`	`'adjust.cn'`： `'adjust.com'`	`true`	`false`
`adjustConfig.UrlStrategyCnOnly`	`'adjust.cn'`	`true`	`false`
`adjustConfig.UrlStrategyIndia`	`'adjust.net.in'`： `'adjust.com'`	`true`	`false`

示例

adjustConfig.setUrlStrategy(['adjust.net.in', 'adjust.com'], true, false);

adjustConfig.setUrlStrategy(['adjust.world', 'adjust.com'], true, false);

adjustConfig.setUrlStrategy(['adjust.cn'], true, false);

adjustConfig.setUrlStrategy(['eu.adjust.com'], true, true);

adjustConfig.setUrlStrategy(['tr.adjust.com'], true, true);

adjustConfig.setUrlStrategy(['us.adjust.com'], true, true);

本节介绍 SDK v5 中对第三方分享功能的变更。

在 SDK v4 中，您可以调用Adjust.disableThirdPartySharing方法来全面禁用第三方信息分享。

Adjust.disableThirdPartySharing();

SDK v5 中已删除该功能。在 SDK v5 中，使用Adjust.trackThirdPartySharing方法来启用或禁用第三方共享。

AdjustThirdPartySharing thirdPartySharing = new AdjustThirdPartySharing(false);
Adjust.trackThirdPartySharing(thirdPartySharing);

广告收入

本节介绍 SDK v5 中对广告收入功能的变更。

记录广告收入

在 SDK v4 中，您可以通过调用trackAdRevenue方法并传递source和payload作为参数来记录广告收入。

Adjust.trackAdRevenue('source', 'payload');

通过 SDK v4 中的新方法，您可以创建带有source的新AdjustAdRevenue对象并将该对象传递至trackAdRevenueNew方法来记录广告收入。

AdjustAdRevenue adRevenue = new AdjustAdRevenue('source');
adRevenue.setRevenue(6, 'CAD');
Adjust.trackAdRevenueNew(adRevenue);

在 SDK v5 中，您需要使用source来创建新的AdjustAdRevenue对象并通过将此对象传递至trackAdRevenue方法来记录广告收入。

AdjustAdRevenue adRevenue = new AdjustAdRevenue('source');
adRevenue.setRevenue(6, 'CAD');
Adjust.trackAdRevenue(adRevenue);

发送特定来源的广告收入

在 SDK v4 中，广告收入来源被定义为adjustConfig类中的常量。在 SDK v5 中，广告收入来源需要以字符串形式传递。

AdjustAdRevenue adRevenue = new AdjustAdRevenue(AdjustConfig.AdRevenueSourceAppLovinMAX);
AdjustAdRevenue adRevenue = new AdjustAdRevenue('applovin_max_sdk');

v4	v5
`adjustConfig.AdRevenueAppLovinMAX`	`'applovin_max_sdk'`
`adjustConfig.AdRevenueSourceAdMob`	`'admob_sdk'`
`adjustConfig.AdRevenueSourceIronSource`	`'ironsource_sdk'`
`adjustConfig.AdRevenueSourceAdMost`	`'admost_sdk'`
`adjustConfig.AdRevenueSourceUnity`	`'unity_sdk'`
`adjustConfig.AdRevenueSourceHeliumChartboost`	`'helium_chartboost_sdk'`
`adjustConfig.AdRevenueSourceADX`	`'adx_sdk'`
`adjustConfig.AdRevenueSourcePublisher`	`'publisher_sdk'`
`adjustConfig.AdRevenueSourceTradplus`	`'tradplus_sdk'`
`adjustConfig.AdRevenueSourceTopOn`	`'topon_sdk'`
`adjustConfig.AdRevenueSourceMopub`	不再支持

SKAdNetwork 和 ATT

本节介绍 SDK v5 中对 SKAdNetwork 和 App Tracking Transparency (ATT) 功能的变更。

关闭 SKAdNetwork 通讯

在 SDK v4 中，您可以通过调用adjustConfig.deactivateSKAdNetworkHandling方法来阻止 SDK 与 SKAdNetwork 通讯。

adjustConfig.deactivateSKAdNetworkHandling();

在 SDK v5 中，您需要将adjustConfig实例的isSkanAttributionEnabled属性设置为false，以此禁用 SKAdNetwork 通讯。

adjustConfig.isSkanAttributionEnabled = false;

监听转化值更新

在 SDK v4 中您可以使用adjustConfig的skad4conversionValueUpdatedCallback属性来监听转化值更新。在 SKAN4 之前，您可以使用conversionValueUpdatedCallback属性。

// pre-SKAN4 callback
adjustConfig.conversionValueUpdatedCallback = (num? conversionValue) {
};


// SKAN4 callback
adjustConfig.skad4ConversionValueUpdatedCallback = (num? conversionValue, String? coarseValue, bool? lockWindow) {
};

在 SDK v5 中，您需要将回传函数指定给adjustConfig实例的skanUpdatedCallback属性。

config.skanUpdatedCallback = (Map<String, String> skanUpdateData) {
  print('[Adjust]: Received SKAN update information!');
  if (skanUpdateData["conversion_value"] != null) {
    print('[Adjust]: Conversion value: ' + skanUpdateData["conversion_value"]!);
  }
  if (skanUpdateData["coarse_value"] != null) {
    print('[Adjust]: Coarse value: ' + skanUpdateData["coarse_value"]!);
  }
  if (skanUpdateData["lock_window"] != null) {
    print('[Adjust]: Lock window: ' + skanUpdateData["lock_window"]!);
  }
  if (skanUpdateData["error"] != null) {
    print('[Adjust]: Error: ' + skanUpdateData["error"]!);
  }
};

更新转化值

在 SDK v4 中，您可以使用以下方法之一向 Adjust 发送更新后转化值：

Adjust.updateConversionValue(6);

Adjust.updateConversionValueWithErrorCallback(6).then((error) {
    // error is present in case it happened
});

Adjust.updateConversionValueWithErrorCallbackSkad4(6, 'coarse-value', true).then((error) {
    // error is present in case it happened
});

如需更新 SDK v5 中的转化值，请使用带下列参数的updateSkanConversionValue方法：

conversionValue ( int )：更新后的转化值
coarseValue ( string )：更新后的粗粒度转化值
lockWindow (bool)：是否在转化窗口结束前发送回调

Adjust.updateSkanConversionValue(6, 'coarse-value', true).then((error) {
    // error is present in case it happened
});

App Tracking Transparency 授权包装器

在 SDK v4 中，您可以使用Adjust.requestTrackingAuthorizationWithCompletionHandler方法处理用户 ATT 授权状态变更。

Adjust.requestTrackingAuthorizationWithCompletionHandler().then((status) {
  print('[Adjust]: Authorization status update!');
  switch (status) {
    case 0:
      print(
          '[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusNotDetermined');
      break;
    case 1:
      print(
          '[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusRestricted');
      break;
    case 2:
      print(
          '[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusDenied');
      break;
    case 3:
      print(
          '[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusAuthorized');
      break;
  }
});

为清晰起见，该参数在 SDK v5 中被重命名为Adjust.requestAppTrackingAuthorization 。

Adjust.requestAppTrackingAuthorization().then((status) {
  print('[Adjust]: Authorization status update!');
  switch (status) {
    case 0:
      print(
          '[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusNotDetermined');
      break;
    case 1:
      print(
          '[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusRestricted');
      break;
    case 2:
      print(
          '[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusDenied');
      break;
    case 3:
      print(
          '[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusAuthorized');
      break;
  }
});

SDK v5 迁移指南

操作前须知

安装 SDK

变更

初始化方法

配置

禁用或启用 SDK

在后台发送信息

预安装应用监测

禁用 AdServices 信息读取

禁用 IDFA 读取

在归因中启用成本数据

启用 LinkMe

只读取设备 ID 一次

离线模式

事件缓冲

自定义用户代理字符串

设置设备是否已知

延迟 SDK 启动

最终安卓归因

AdjustEvent 变更

记录功能

会话回传参数

会话合作伙伴参数

发送订阅信息

App Store 订阅

App Store 购买

Play 商店订阅

深度链接

通过深度链接进行再归因

启动延迟深度链接

深度链接解析

隐私功能

《儿童在线隐私权保护法》(COPPA) 合规

Play Store 儿童应用

设置数据驻留和 URL 策略

示例

第三方分享变更

全局禁用第三方分享

广告收入

记录广告收入

发送特定来源的广告收入

SKAdNetwork 和 ATT

关闭 SKAdNetwork 通讯

监听转化值更新

更新转化值

App Tracking Transparency 授权包装器