接入细节

Android

一、SDK 集成

1. 确保已经完成了 XDSDK 的基础集成，具体请参考基础集成。

2. 确保已添加 XDSDK 推送模块。在项目级别的 build.gradle 文件中添加 XDSDK 推送模块的依赖。

   // 推送模块
   implementation files('libs/XDGPush_6.23.5.aar')
   // 针对国内阿里云推送需集成
   implementation files('libs/XDGPushCN_6.23.5.aar')
   // 针对海外 Firebase 推送需集成
   implementation files('libs/XDGPushGlobal_6.23.5.aar')

3. 针对国内的推送，需添加推送的仓库地址。

   AGP 7.0+ 版本及以上使用 dependencyResolutionManagement 方式，在项目根目录的 settings.gradle 文件中添加推送的仓库地址。

   dependencyResolutionManagement {
      repositories {
         // ...
         // 阿里云推送
         maven { url 'https://maven.aliyun.com/nexus/content/repositories/releases/' }
         // 集成华为辅助通道推送时，需要配置 HMS Core SDK 的仓库地址
         maven { url 'https://developer.huawei.com/repo/' }
      }
   }

   AGP 7.0+ 以下使用 allprojects 方式，在项目根目录的 build.gradle 文件中添加推送的仓库地址。

   allprojects {
       repositories {
           // ...
           // 阿里云推送
           maven { url 'https://maven.aliyun.com/nexus/content/repositories/releases/' }
           // 当需要使用华为辅助通道推送时，需要添加华为推送的仓库地址
           maven { url 'https://developer.huawei.com/repo/' }
       }
   }

4. 添加三方 SDK 推送依赖。在应用级别的 Gradle 文件：<project>/<app>/build.gradle 中按需添加对应的推送平台集成。

   国内：

   dependencies {
       // 阿里云推送主 SDK
       implementation 'com.aliyun.ams:alicloud-android-push:3.9.1'
       
       // 针对国内不同手机厂商的推送，可以集成辅助通道 SDK
       implementation 'com.aliyun.ams:alicloud-android-third-push:3.9.0' // 阿里云辅助通道推送（使用以下辅助通道时必需，否则可不集成）
       implementation 'com.aliyun.ams:alicloud-android-third-push-huawei:3.9.0' // 阿里云辅助通道推送华为
       implementation 'com.aliyun.ams:alicloud-android-third-push-honor:3.9.0' // 阿里云辅助通道推送荣耀
       implementation 'com.aliyun.ams:alicloud-android-third-push-meizu:3.9.0' // 阿里云辅助通道推送魅族
       implementation 'com.aliyun.ams:alicloud-android-third-push-xiaomi:3.9.0' // 阿里云辅助通道推送小米
       implementation 'com.aliyun.ams:alicloud-android-third-push-vivo:3.9.0' // 阿里云辅助通道推送 vivo
       implementation 'com.aliyun.ams:alicloud-android-third-push-oppo:3.9.0' // 阿里云辅助通道推送 oppo
   }

   海外：

   dependencies {
       // Firebase Cloud Messaging
       implementation 'com.google.firebase:firebase-messaging:23.4.1'
       // Firebase Analytics（使用 Firebase 推送时需要搭配数据分析使用）
       implementation 'com.google.firebase:firebase-analytics:21.3.0'
   }

二、添加配置

1. 配置 XDConfig.json 文件。

   如快速接入中的 XDConfig.json 配置所示，添加阿里云推送配置：

   {
      // 其他配置
       "aliyun": {
           "push_key_android": "{your_push_key_android}",
           "push_secret_android": "{your_push_secret_android}"
       }
   }

2. 配置 AndroidManifest.xml 文件。

   使用阿里云辅助通道时，根据需要添加厂商辅助通道添加对应的配置，将示例中描述部分替换为正确值。请注意格式。

   <manifest>
     <application>
          <!-- 华为通道 -->
          <meta-data
              android:name="com.huawei.hms.client.appid"
              android:value="appid=华为 AppID" />
          <!-- 荣耀通道 -->
          <meta-data
              android:name="com.hihonor.push.app_id"
              android:value="荣耀 AppID" />
          <!-- 小米通道 -->
          <meta-data
              android:name="com.xd.xiaomi.push.app_id"
              android:value="id=小米 AppID" />
          <meta-data
              android:name="com.xd.xiaomi.push.app_key"
              android:value="id=小米 AppKey" />
          <!-- oppo 通道 -->
          <meta-data
              android:name="com.xd.oppo.push.app_key"
              android:value="id=OPPO AppKey" />
          <meta-data
              android:name="com.xd.oppo.push.app_secret"
              android:value="id=OPPO AppSecret" />
          <!-- vivo 通道 -->
          <meta-data
              android:name="com.vivo.push.api_key"
              android:value="VIVO ApiKey" />
          <meta-data
              android:name="com.vivo.push.app_id"
              android:value="VIVO AppID" />
          <!-- 魅族通道 -->
          <meta-data
              android:name="com.xd.meizu.push.app_id"
              android:value="id=魅族 AppID" />
          <meta-data
              android:name="com.xd.meizu.push.app_key"
              android:value="id=魅族 AppKey" />
     </application>
   </manifest>

三、在 Android 13 及更高版本上请求运行时通知权限

Android 13 中引入了用于显示通知的新运行时权限。该项引入会影响在 Android 13 或更高版本上使用通知的所有应用。

默认情况下，如果是国内应用，需要在 AndroidManifest.xml 文件中添加 POST_NOTIFICATIONS 权限。 如果是海外应用，Firebase Cloud Messaging 库会自动在 AndroidManifest.xml 文件中添加所需的权限。

此外，还需针对 Android 13 及更高版本的设备请求运行时通知权限。以下是请求通知权限的示例代码：

// Declare the launcher at the top of your Activity/Fragment:
private final ActivityResultLauncher<String> requestPermissionLauncher =
        registerForActivityResult(new ActivityResultContracts.RequestPermission(), isGranted -> {
            if (isGranted) {
                // 已有推送通知权限
            } else {
                // TODO: 没有通知权限，可以告知用户应用的某些功能将受到限制
            }
        });

private void askNotificationPermission() {
    // This is only necessary for API level >= 33 (TIRAMISU)
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
                PackageManager.PERMISSION_GRANTED) {
            // 已有推送通知权限
        } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) {
            // TODO: 可以在这里向用户解释为什么需要通知权限
        } else {
            // 直接请求通知权限
            requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS);
        }
    }
}

四、关于通知栏图标

在 Android 12 及更高版本上，通知栏图标的行为发生了变化。在 Android 12 及更高版本上，通知栏图标将被应用的前景色覆盖。为了避免这种情况，游戏可以使用透明的通知栏图标。

阿里云推送

国内阿里云推送通知，默认会获取 ID 为 R.drawable.alicloud_notification_largeicon 的图标作为通知栏图标；默认会获取 ID 为 R.drawable.alicloud_notification_smallicon 的图标作为状态栏图标。 如果没有提供图标，阿里云推送会使用应用启动图标作为通知栏、状态栏图标。

Firebase 推送

海外 Firebase 推送通知可以在 AndroidManifest.xml 文件中添加配置修改默认使用的通知栏图标。 如果没有提供这个图标，Firebase 推送会使用应用启动图标作为通知栏图标。

<manifest>
   <application>
      <meta-data
              android:name="com.google.firebase.messaging.default_notification_icon"
              android:resource="@drawable/通知图标资源 ID"/>

      <meta-data
              android:name="com.google.firebase.messaging.default_notification_color"
              android:resource="@color/通知图标颜色资源 ID"/>
   </application>
</manifest>

五、关于系统通知渠道

在 Android 8.0 及更高版本上，通知必须分配到通知渠道。通知渠道允许用户对不同类型的通知进行分类，以便用户可以更好地控制通知的显示方式。 SDK 内部已包含默认的通知渠道，如果游戏需要自定义通知渠道名称，在 XDConfig.json 配置文件中增加以下配置：

{
   // 其他配置
   "push_config": {
      "channel_name_android": "Customer Push"
   }
}

iOS

一、添加 SDK 依赖

需要包含 XDAccountSDK.framework，XDCommonSDK.framework 两个基础模块

如果是国内需要再添加 XDAliPushWrapperSDK.framework，海外添加 XDFirebasePushWrapperSDK.framework。

二、开启开发项目的推送权限

要在应用程序中添加所需的权限，请在 Xcode 项目中启用推送通知功能。

打开 Xcode 项目，在 Project > Target > Capabilities 页面中点击红框中的加号按钮，然后选择并添加 Push Notifications。

Unity

暂无

UE

一、开启插件和添加模块依赖

1. 确保开启插件 XDGPush
2. 确保国内或海外开启插件 XDGMainland 或 XDGOverseas （插件包含了分享用到的三方 SDK）
3. ModuleRules 的 PrivateDependencyModuleNames 或 PublicDependencyModuleNames 添加依赖模块 XDGPush

二、配置 iOS

在文件 DefaultEngine.ini 添加如下配置：

[/Script/IOSRuntimeSettings.IOSRuntimeSettings]
bEnableRemoteNotificationsSupport=True

在文件 DefaultXDGConfig.ini 添加如下配置：

aliyun__push_key_ios=阿里云推送 iOS AppKey
aliyun__push_secret_ios=阿里云推送 iOS AppSecret

三、配置 Android

在文件 DefaultXDGConfig.ini 添加如下配置：

aliyun__push_key_android=阿里云推送 Android AppKey
aliyun__push_secret_android=阿里云推送 Android AppSecret

针对国内不同手机厂商的推送，可以集成辅助通道 SDK，具体配置如下：

aliyun__auxiliary_channel__xiaomi__app_id=小米推送 AppID
aliyun__auxiliary_channel__xiaomi__app_key=小米推送 AppKey
aliyun__auxiliary_channel__huawei__app_id=华为推送 AppID
aliyun__auxiliary_channel__honor__app_id=荣耀推送 AppID
aliyun__auxiliary_channel__vivo__app_id=VIVO AppID
aliyun__auxiliary_channel__vivo__api_key=VIVO ApiKey
aliyun__auxiliary_channel__oppo__app_key=OPPO AppKey
aliyun__auxiliary_channel__oppo__app_secret=OPPO AppSecret
aliyun__auxiliary_channel__meizu__app_id=魅族 AppID
aliyun__auxiliary_channel__meizu__app_key=魅族 AppKey