Cocos2d-x SDK 集成指南

通过 Adjust安卓SDK，您可以在 Cocos2d-x 应用中记录归因、事件及更多数据。请按照本指南中说明的步骤操作，在应用内设置 Adjust SDK。

1. 安装 SDK

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

从 GitHub下载 SDK 档案
复制dist目录下的 C++ 文件，将其添加进 Cocos2d-x 项目

( 仅限安卓 )将 C++ 文件的路径添加到Android.mk文件的LOCAL_SRC_FILES部分。

$(LOCAL_PATH)/../../../Classes/Adjust/AdjustConfig2dx.cpp \
$(LOCAL_PATH)/../../../Classes/Adjust/AdjustAttribution2dx.cpp \
$(LOCAL_PATH)/../../../Classes/Adjust/AdjustProxy2dx.cpp \
$(LOCAL_PATH)/../../../Classes/Adjust/AdjustEvent2dx.cpp \
$(LOCAL_PATH)/../../../Classes/Adjust/Adjust2dx.cpp \
$(LOCAL_PATH)/../../../Classes/Adjust/AdjustEventFailure2dx.cpp \
$(LOCAL_PATH)/../../../Classes/Adjust/AdjustEventSuccess2dx.cpp \
$(LOCAL_PATH)/../../../Classes/Adjust/AdjustSessionFailure2dx.cpp \
$(LOCAL_PATH)/../../../Classes/Adjust/AdjustSessionSuccess2dx.cpp \
$(LOCAL_PATH)/../../../Classes/Adjust/AdjustAppStoreSubscription2dx.cpp \
$(LOCAL_PATH)/../../../Classes/Adjust/AdjustPlayStoreSubscription2dx.cpp \
$(LOCAL_PATH)/../../../Classes/Adjust/AdjustThirdPartySharing2dx.cpp \
$(LOCAL_PATH)/../../../Classes/Adjust/AdjustAdRevenue2dx.cpp
$(LOCAL_PATH)/../../../Classes/Adjust/AdjustAppStorePurchase2dx.cpp \
$(LOCAL_PATH)/../../../Classes/Adjust/AdjustPlayStorePurchase2dx.cpp \
$(LOCAL_PATH)/../../../Classes/Adjust/AdjustDeeplink2dx.cpp \
$(LOCAL_PATH)/../../../Classes/Adjust/AdjustPurchaseVerificationResult2dx.cpp \

如果您使用 CMake，请将以下来源和标头列表添加至您的CMakeLists.txt文件：

# add cross-platforms source files and header files
list(APPEND GAME_SOURCE
    Classes/Adjust/AdjustConfig2dx.cpp
    Classes/Adjust/AdjustAttribution2dx.cpp
    Classes/Adjust/AdjustProxy2dx.cpp
    Classes/Adjust/AdjustEvent2dx.cpp
    Classes/Adjust/AdjustAdRevenue2dx.cpp
    Classes/Adjust/AdjustAppStoreSubscription2dx.cpp
    Classes/Adjust/AdjustPlayStoreSubscription2dx.cpp
    Classes/Adjust/AdjustAppStorePurchase2dx.cpp
    Classes/Adjust/AdjustPlayStorePurchase2dx.cpp
    Classes/Adjust/Adjust2dx.cpp
    Classes/Adjust/AdjustEventFailure2dx.cpp
    Classes/Adjust/AdjustEventSuccess2dx.cpp
    Classes/Adjust/AdjustSessionFailure2dx.cpp
    Classes/Adjust/AdjustSessionSuccess2dx.cpp
    Classes/Adjust/AdjustThirdPartySharing2dx.cpp
    Classes/Adjust/AdjustDeeplink2dx.cpp
    Classes/Adjust/AdjustPurchaseVerificationResult2dx.cpp
    )
list(APPEND GAME_HEADER
    Classes/Adjust/AdjustConfig2dx.h
    Classes/Adjust/AdjustAttribution2dx.h
    Classes/Adjust/AdjustProxy2dx.h
    Classes/Adjust/AdjustEvent2dx.h
    Classes/Adjust/AdjustAdRevenue2dx.h
    Classes/Adjust/AdjustAppStoreSubscription2dx.h
    Classes/Adjust/AdjustPlayStoreSubscription2dx.h
    Classes/Adjust/AdjustAppStorePurchase2dx.h
    Classes/Adjust/AdjustPlayStorePurchase2dx.h
    Classes/Adjust/Adjust2dx.h
    Classes/Adjust/AdjustEventFailure2dx.h
    Classes/Adjust/AdjustEventSuccess2dx.h
    Classes/Adjust/AdjustSessionFailure2dx.h
    Classes/Adjust/AdjustSessionSuccess2dx.h
    Classes/Adjust/AdjustThirdPartySharing2dx.h
    Classes/Adjust/AdjustDeeplink2dx.h
    Classes/Adjust/AdjustPurchaseVerificationResult2dx.h
    )

( 仅限安卓 )：从GitHub 发布页面下载最新的adjust-android.aar并将其导入您的 Android Studio 项目中。
( 仅限 iOS )：从GitHub 发布页面下载最新的AdjustSdk.framework并将其链接到您的 Xcode 项目中。

2. 设置签名库

SDK v5 使用SDK 签名库来加密从 Adjust SDK 发送到 Adjust 服务器的信息。您必须将签名库添加到项目中才能使用 SDK v5。

安卓应用

从Adjust 签名库 GitHub 库下载最新的adjust-android-signature.aar 。
将.aar添加至您的 Android Studio 项目。

iOS 应用

从Adjust 签名库 GitHub 库下载最新的AdjustSigSdk-iOS-Static.a 。
请在您的 Xcode 项目中关联.a。

3. 配置安卓设置

按照以下步骤为安卓设备配置 Adjust SDK。

权限

Adjust 安卓 SDK 已预先配置了所需的权限。其中包括com.google.android.gms.permission.AD_ID权限。如果您的应用需要符合《儿童在线隐私保护法》(COPPA) 的规定，则必须通过将以下内容添加到AndroidManifest.xml文件来删除此权限：

<uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove" id="sl-md0000000"/>

要进一步了解 COPPA，请参阅Adjust 的 COPPA 合规文档。

添加 Google Play 服务

定向 Google Play 商店的应用必须使用 Google 广告 ID (gps_adid) 来识别设备。为此，请将以下 dependency 加入build.gradle 文件的 dependencies 部分。

dependencies: {
   implementation 'com.google.android.gms:play-services-ads-identifier:18.1.0'
}

设置 Install Referrer

Install Referrer 是一种归因机制，可用来将应用安装归因至来源。包含两部分：

来自这些 App Store 的一组 API，允许开发者在其应用中调取推荐内容。
Google Play 和华为 App Gallery 等应用商店在其商店网站应用页面 URL 中接受的 referrer 参数。referrer 参数按以下方式填充：
- 用户点击 Adjust 链接时，Adjust 服务器发送一个独一无二的识别码，即 reftag。该识别码被指配给此点击，并被添加至 referrer 参数。要了解有关 reftag 的更多信息，请参阅帮助中心的 reftag 文档。
- 您在开展 Google Ads 推广活动时，Google 会传递一个叫做 gclid 的唯一识别码至 referrer 参数。您必须在 Google Ads 账户中启用 自动标记 。

Google Play Referrer API

要支持Google Play Referrer API，请按照下列步骤操作：

在build.gradle文件中添加 Google Maven 库。

allprojects {
   repositories {
      maven {
         url "https://maven.google.com"
      }
   }
}

将 Install Referrer 库添加至您的build.gradle文件。

dependencies {
   implementation 'com.android.installreferrer:installreferrer:2.2'
}

Meta Install Referrer

要添加对Meta Install Referrer的支持，请按照下列步骤操作：

通过添加下列 dependency 至您的build.gradle文件来安装 Adjust 安卓 Meta Referrer 插件：
```
dependencies {
   implementation 'com.adjust.sdk:adjust-android-meta-referrer:5.0.1'
}
```
在Meta 应用控制面板中找到您的 Meta app ID。

使用 Meta App ID 作为参数在 AdjustConfig2dx 实例上调用 setFbAppId 方法。

#include "Adjust/Adjust2dx.h"

std::string appToken = "{YOUR_APP_TOKEN}";
std::string environment = AdjustEnvironmentSandbox2dx;

AdjustConfig2dx adjustConfig = AdjustConfig2dx(appToken, environment);
adjustConfig.setFbAppId("{YOUR_FB_APP_ID}");
Adjust2dx::initSdk(adjustConfig);

4. 配置 iOS 设置

按照以下步骤为 iOS 设备配置 Adjust SDK。

关联其他框架

将下列框架关联至您的 Xcode 项目，为 Adjust SDK 提供设备层级信息的访问权限。

框架	用途	注意事项
`AdSupport.framework`	Adjust SDK 读取设备 IDFA 必需。	如果您的应用属于 "儿童" 类别，那么请勿添加该框架
`AdServices.framework`	处理 Apple Search Ads 必需
`StoreKit.framework`	访问 SKAdNetwork 框架以及 Adjust SDK 处理与 SKAdNetwork 之间的通讯时必需。
`AppTrackingTransparency.framework`	在 iOS 14 及更高版本中必需，以便 Adjust SDK 包装 ATT 许可对话框并访问用户的许可响应。	如果您的应用属于 "儿童" 类别，那么请勿添加该框架

复制其他源文件

要完成 iOS 设置，您必须将 SDK 解压文件dist目录中的所有 Objective-C++ ( .h和.mm ) 文件复制到您的 Xcode 项目中。确保所有.mm文件都列在 Build Phases --> Compile Sources 部分中。

更新应用的隐私清单

要向 App Store 通知 Adjust SDK 的隐私要求，您需要将您的隐私清单与 Adjust 的隐私清单合并。

将Adjust SDK 隐私清单属性添加至应用的隐私清单。
将签名库隐私清单属性添加至应用的隐私清单。

7. 集成 Adjust SDK

更新项目设置后，您就可以将 Adjust SDK 集成到应用中了。为此请进行下列操作：

在 项目导航 中找到并打开应用委托文件。
在文件顶部包含Adjust/Adjust2dx.h类。
使用以下参数实例化AdjustConfig2dx对象：
appToken (std::string)
您的 Adjust 应用识别码
environment (std::string)
通过传递AdjustEnvironmentSandbox2dx在 sandbox 环境中测试您的应用。
您也可以通过调整日志级别来调整日志的详细程度。
应用启动后，尽快调用Adjust2dx::initSdk方法并将AdjustConfig2dx实例作为参数传递。

#include "Adjust/Adjust2dx.h"

std::string appToken = "{YOUR_APP_TOKEN}";
std::string environment = AdjustEnvironmentSandbox2dx;

AdjustConfig2dx adjustConfig = AdjustConfig2dx(appToken, environment);
adjustConfig.setLogLevel(AdjustLogLevel2dxVerbose);
Adjust2dx::initSdk(adjustConfig);

6. 构建您的应用

完成了！您现在可以创建并运行 Cocos2d-x 应用了。请启用日志，检查可能存在的问题。请查看日志中的 Install tracked 信息。