adjust-icon

iOS Web bridge v5 迁移指南

操作前须知

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

  1. SDK v5 支持SDK 签名验证。如果您当前正在使用 SDK 签名库，则需要先将其卸载。
  2. 如果您的应用针对低于以下版本的 API，则需要先更新应用才能使用 SDK v5：
    • iOS: 12.0
    • tvOS: 12.0

安装 SDK

要开始使用 SDK v5，您需要将其添加为 XCode 项目的依赖。为此请进行下列操作：

  1. 请移除Podfile中所有较旧版本的 SDK。

  2. 添加下列行至您的 Podfile：

    Podfile
    pod 'Adjust/AdjustWebBridge', :git => 'https://github.com/adjust/ios_sdk.git', :tag => 'v5.0.0'

  3. 运行pod install来安装依赖。

变更

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

初始化方法

在 SDK v4 中，初始化方法为Adjust.onCreate(AdjustConfig) 。在 SDK v5 中，该方法已变为Adjust.initSdk(AdjustConfig) 。

const adjustConfig = new AdjustConfig(this, appToken, environment);


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

配置

本节介绍 SDK 配置变更。

禁用 IDFA 读取

在 SDK v5 中，您可以通过在AdjustConfig实例上调用disableIdfaReading方法来阻止 Adjust SDK 读取广告主设备 ID (IDFA)。

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.disableIdfaReading();

禁用 AdServices 信息读取

在 SDK v4 中，您可以使用false参数调用AdjustConfig实例的setAllowAdServicesInfoReading方法，阻止 Adjust SDK 读取 AdServices 信息。

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setAllowAdServicesInfoReading(false);

在 SDK v5 中，您需要调用不带参数的disableAdServices方法以防止 Adjust SDK 读取 AdServices 信息。

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.disableAdServices();

禁用或启用 SDK

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

  • 调用Adjust.setEnabled(false)来禁用 SDK。
  • 调用Adjust.setEnabled(true)来启用 SDK。
Adjust.setEnabled(false); // disable SDK
Adjust.setEnabled(true); // enable SDK

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

  • 调用Adjust.disable()来禁用 SDK。
  • 调用Adjust.enable()来启用 SDK。
Adjust.disable(); // disable SDK
Adjust.enable(); // enable SDK

离线模式

在 SDK v4 中，您可以通过调用带有boolean值的Adjust.setOfflineMode()来启用或禁用 SDK 中的离线模式。

Adjust.setOfflineMode(false); // put SDK in offline mode
Adjust.setOfflineMode(true); // put SDK back in online mode

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

  • 调用Adjust.switchToOfflineMode()将 SDK 设为离线模式。
  • 调用Adjust.switchBackToOnlineMode()将 SDK 重新设为在线模式。
Adjust.switchToOfflineMode(); // put SDK in offline mode
Adjust.switchBackToOnlineMode(); // put SDK back in online mode

在归因中启用成本数据

在 SDK v4 中，您可以使用布尔参数调用AdjustConfig实例的setNeedsCost方法，使用 SDK 在用户归因数据中发送成本数据。

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setNeedsCost(true);

在 SDK v5 中，为清晰起见，该方法已被重命名为enableCostDataInAttribution 。这种新方法不带参数。

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.enableCostDataInAttribution();

事件缓冲

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

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setEventBufferingEnabled(true);

SDK v5 中已删除该设置。

自定义用户代理字符串

SDK v4 支持使用用户代理字符串调用AdjustConfig实例的setUserAgent方法来设置自定义用户代理。

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setUserAgent("user_agent_value");

SDK v5 中已删除该设置。

设置设备是否已知

在 SDK v4 中，您可以调用AdjustConfig实例的setDeviceKnown方法，手动告知 SDK 设备是否为已知设备。

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setDeviceKnown(true);

SDK v5 中已删除该设置。

延迟 SDK 启动

SDK v4 支持通过在AdjustConfig实例上调用setDelayStart方法来延迟 SDK 启动，最多延迟 120 秒 。如果应用在延迟结束前就绪，则可以通过调用Adjust.sendFirstPackages立即发送信息。

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setDelayStart(delay);


Adjust.sendFirstPackages();

在 SDK v5 中这两种方法都已被移除。

setPushToken

SDK v4 支持通过您的推送标签 (Push token) 调用Adjust.setDeviceToken来设置设备推送标签。

Adjust.setDeviceToken(deviceToken);

SDK v5 中已删除该功能。

记录功能

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

会话回传参数

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

Adjust.addSessionCallbackParameter("foo", "bar");
Adjust.removeSessionCallbackParameter("foo");
Adjust.resetSessionCallbackParameters();


Adjust.addGlobalCallbackParameter("foo", "bar");
Adjust.removeGlobalCallbackParameter("foo");
Adjust.removeGlobalCallbackParameters();

会话合作伙伴参数

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

Adjust.addSessionPartnerParameter("foo", "bar");
Adjust.removeSessionPartnerParameter("foo");
Adjust.resetSessionPartnerParameters();


Adjust.addGlobalPartnerParameter("foo", "bar");
Adjust.removeGlobalPartnerParameter("foo");
Adjust.removeGlobalPartnerParameters();

事件数据去重

在 SDK v4 中，事件去重与事件order ID同时进行且唯一 ID 的数量上限为 10 个。

const event = new AdjustEvent("event_token");
event.setOrderId("deduplication_id");
Adjust.trackEvent(event);

在 SDK v5 中，该功能与order ID分离。事件去重添加了名为deduplicationId的新 ID 字段。用户可以自定义deduplicationId的数量限制，添加到用于识别重复事件的列表中。默认情况下，上限为 10 。

const adjustConfig = new AdjustConfig(this, appToken, environment);


adjustConfig.setEventDeduplicationIdsMaxSize(20); // if not set, then 10
Adjust.initSdk(adjustConfig);


const event = new AdjustEvent("event_token");
event.setDeduplicationId("deduplication_id");
Adjust.trackEvent(event);

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

在 SDK v5 中，您可以通过调用AdjustConfig实例的disableDeferredDeeplinkOpening方法来阻止 SDK 打开延迟深度链接。

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.disableDeferredDeepLinkOpening();

在 SDK v4 中，您可以在 Web bridge 中通过调用Adjust.appWillOpenUrl()方法向 Adjust 发送深度链接 URL。

Adjust.appWillOpenUrl(data, getApplicationContext());

该方法在 SDK v5 中已被移除。

Adjust LinkMe

在 SDK v4 中，您可以使用 Adjust 网桥，通过布尔参数调用AdjustConfig实例的setLinkMeEnabled方法来启用Adjust LinkMe 。

setupWebViewJavascriptBridge(function (bridge) {
   var yourAppToken = yourAppToken;
   var environment = AdjustConfig.EnvironmentSandbox;
   var adjustConfig = new AdjustConfig(yourAppToken, environment);
   adjustConfig.setLinkMeEnabled(true);
});

该方法在 SDK v5 中已被移除。

隐私功能

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

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

在 SDK v4 中，您可以通过布尔参数在AdjustConfig实例上调用setCoppaCompliantEnabled方法来设置COPPA 合规性。

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setCoppaCompliantEnabled(true);

在 SDK v5 中，为清晰起见，该方法已被重命名为enableCoppaCompliance 。该新方法不接受任何参数。

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.enableCoppaCompliance();

发送特定来源的广告收入

在SDK v4 中，您可以发送来源和负载至 Adjust.trackAdRevenue() 方法来发送特定来源的广告收入。

Adjust.trackAdRevenue(source, payload);

该方法在 SDK v5 中已被移除。

设置数据驻留和 URL 策略

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

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setUrlStrategy(AdjustConfig.DataResidencyEU);

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

  • useSubdomains ( boolean )：来源是否为子域名作为前缀。
  • isDataResidency ( boolean )：域名是否用于数据驻留。
const adjustConfig = new AdjustConfig(this, appToken, environment);
const domains = ["domain1", "domain2"];
const useSubdomains = true;
const isDataResidency = false;
adjustConfig.setUrlStrategy(domains, useSubdomains, isDataResidency);

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

示例
印度 URL 策略
const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setUrlStrategy(["adjust.net.in", "adjust.com"], true, false);
中国 URL 策略
const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setUrlStrategy(["adjust.world", "adjust.com"], true, false);
仅限中国地区的 URL 策略
const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setUrlStrategy(["adjust.cn"], true, false);
欧盟数据驻留
const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setUrlStrategy(["eu.adjust.com"], true, true);
土耳其数据驻留
const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setUrlStrategy(["tr.adjust.com"], true, true);
数据驻留
const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setUrlStrategy(["us.adjust.com"], true, true);

全局禁用第三方分享

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

Adjust.disableThirdPartySharing();

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

const adjustThirdPartySharing = new AdjustThirdPartySharing(true);
Adjust.trackThirdPartySharing(adjustThirdPartySharing);

SKAdNetwork 和 ATT

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

禁用 SKAdNetwork 归因

在 SDK v5 中，您可以调用AdjustConfig实例的disableSkanAttributionHandling方法来阻止 Adjust SDK 向 Apple 的 SKAdNetwork 发送归因信息。

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.disableSkanAttributionHandling();

SKAdNetwork 更新回传

在 SDK v5 中，您可以配置 Adjust SDK，通过使用回传函数调用AdjustConfig实例的setSkanUpdatedCallback方法来在用户 SKAdNetwork 转化值发生变化时执行回传函数。

const adjustConfig = new AdjustConfig(this, appToken, environment);


adjustConfig.setSkanUpdatedCallback(function (skanData) {
   alert("SKAN: " + skanData.error);
});

请求 ATT 授权状态

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

Adjust.requestTrackingAuthorizationWithCompletionHandler(function(status) {
  alert('Permission status\n' + status);
};

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

Adjust.requestAppTrackingAuthorizationWithCompletionHandler(function(status) {
  alert('Permission status\n' + status);
};

查看 ATT 状态

在 SDK v4 中，您可以通过调用Adjust.checkForNewAttStatus方法来检查用户 ATT 状态的变化。

Adjust.checkForNewAttStatus();

该方法在 SDK v5 中已被移除。

获取设备信息

本节介绍 SDK v5 中设备信息 getter 的变更。

设备 ID getter

在 SDK v4 中，所有设备 ID getter 方法都会同步运行。在 SDK v5 中，这些方法已改为异步运行。

ADID getter
Adjust.getAdid(function (adid) {
   alert("Ad Id:\n" + adid);
});
归因信息 getter
Adjust.getAttribution(function (attribution) {
   alert(
      "Tracker token = " +
         attribution.trackerToken +
         "\n" +
         "Tracker name = " +
         attribution.trackerName +
         "\n" +
         "Network = " +
         attribution.network +
         "\n" +
         "Campaign = " +
         attribution.campaign +
         "\n" +
         "Adgroup = " +
         attribution.adgroup +
         "\n" +
         "Creative = " +
         attribution.creative +
         "\n" +
         "Click label = " +
         attribution.clickLabel,
   );
});
SDK 版本 getter
Adjust.getSdkVersion(function (sdkVersion) {
   alert("SDK version:\n" + sdkVersion);
});
启用状态 getter
Adjust.isEnabled(function (isEnabled) {
   alert("Is SDK enabled? " + isEnabled);
});