adjust-icon

SDK v5 迁移指南

操作前须知

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

  1. SDK v5 支持SDK 签名验证。如果您正在使用 SDK 签名库，请先从应用中移除签名库。

  2. SDK v5 支持的最低 API 版本已更新。如果您的应用目标版本较低，请先进行更新。

    • iOS: 12.0
    • 安卓： 21

安装 SDK

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

pubspec.yaml
dependencies:
   adjust_sdk: ^5.0.0

更新初始化方法

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

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

变更 API

于 v5 中变更

SDK v5 中变更了下列 API。

禁用或启用 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 中，您可以通过传递键值对至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();

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';

在 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
};

COPPA 合规

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

adjustConfig.coppaCompliantEnabled = true;

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

adjustConfig.isCoppaComplianceEnabled = true;

Play 商店儿童应用

在 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 策略。

v4v5 - 主要和后备域名v5 - 使用子域名v5 - 数据驻留
adjustConfig.DataResidencyEU'eu.adjust.com'truetrue
adjustConfig.DataResidencyTR'tr.adjust.com'truetrue
adjustConfig.DataResidencyUS'us.adjust.com'truetrue
adjustConfig.UrlStrategyChina'adjust.world', 'adjust.com'truefalse
adjustConfig.UrlStrategyCn'adjust.cn', 'adjust.com'truefalse
adjustConfig.UrlStrategyCnOnly'adjust.cn'truefalse
adjustConfig.UrlStrategyIndia'adjust.net.in', 'adjust.com'truefalse

示例

印度 URL 策略
adjustConfig.setUrlStrategy(['adjust.net.in', 'adjust.com'], true, false);
中国 URL 策略
adjustConfig.setUrlStrategy(['adjust.world', 'adjust.com'], true, false);
仅限中国地区的 URL 策略
adjustConfig.setUrlStrategy(['adjust.cn'], true, false);
欧盟 URL 策略
adjustConfig.setUrlStrategy(['eu.adjust.com'], true, true);
土耳其 URL 策略
adjustConfig.setUrlStrategy(['tr.adjust.com'], true, true);
美国 URL 策略
adjustConfig.setUrlStrategy(['us.adjust.com'], true, true);

记录广告收入

在 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');
v4v5
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 通讯

在 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;
  }
});

移除 API

于 v5 中删除

SDK v5 中移除了下列 API。

事件缓冲

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 中已移除该类属性，因为该类属性已不再用于收入验证。

全局禁用第三方分享

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

Adjust.disableThirdPartySharing();

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

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

设置应用密钥

SDK v4 支持通过在AdjustConfig实例上调用setAppSecret方法来设置应用密钥，以此对 SDK 流量进行签名。

adjustConfig.setAppSecret(secretId, info1, info2, info3, info4);

SDK v5 中已删除该设置。