移动推送
有奖捉虫：办公协同&微信生态&物联网文档专题 HOT
文档中心 > 移动推送 > SDK 文档 > Android 接入指南 > SDK 集成

SDK 集成

最近更新时间：2024-03-29 14:47:31

我的收藏

本页目录：

简介

本文内容引导集成移动推送 SDK 在线通道推送能力，提供 AndroidStudio Gradle 自动集成和 Android Studio 手动集成两种方式指引。如需在应用进程被杀时也能收到推送，请在完成本文的集成操作后，参考 厂商通道接入指南 文档，完成各厂商通道的接入。
注意
为了避免您的 App 被监管部门通报或下架，请您在接入 SDK 之前务必按照 Android 合规指南 在《隐私政策》中增加移动推送相关说明，并且在用户同意《隐私政策》后再初始化移动推送SDK。

SDK 集成（二选一）

AndroidStudio Gradle 自动集成

操作步骤

注意
在配置 SDK 前，确保已创建 Android 平台的应用。
1. 登录 移动推送控制台，在产品管理>配置管理页面获取应用的 AccessID、AccessKey。
2. 在 SDK 下载 页面，获取当前最新版本号。


3. 在 app build.gradle 文件下，配置以下内容：
android {
 ......
 defaultConfig {

     //控制台上注册的包名.注意application ID 和当前的应用包名以及控制台上注册应用的包名必须一致。
     applicationId "您的包名"
     ......

     ndk {
         //根据需要 自行选择添加的对应cpu类型的.so库。
         abiFilters 'armeabi', 'armeabi-v7a', 'arm64-v8a'
         // 还可以添加 'x86', 'x86_64', 'mips', 'mips64'
     }

     manifestPlaceholders = [

         XG_ACCESS_ID : "注册应用的accessid",
         XG_ACCESS_KEY : "注册应用的accesskey",
     ]
     ......
 }
 ......
}

dependencies {
 ......
 //添加以下依赖             
 implementation 'com.tencent.tpns:tpns:[VERSION]-release' 
       // TPNS 推送 [VERSION] 为最新 SDK 版本号，即为上述步骤2获取的版本号
}
注意
如果您的应用服务接入点为广州，SDK 默认实现该配置。
如果您的应用服务接入点为上海、新加坡或中国香港，请按照下文步骤完成其他服务接入点域名配置，否则会导致注册推送服务失败并返回-502或1008003错误码。 在 AndroidManifest 文件 application 标签内添加以下元数据：
<application>
    // 其他安卓组件
    <meta-data
            android:name="XG_SERVER_SUFFIX"
            android:value="其他服务接入点域名" />
</application>
其他服务接入点域名如下：
上海：tpns.sh.tencent.com
新加坡：tpns.sgp.tencent.com
中国香港：tpns.hk.tencent.com

注意事项

如在添加以上 abiFilter 配置后， Android Studio 出现以下提示：
NDK integration is deprecated in the current plugin. Consider trying the new experimental plugin，则在 Project 根目录的 gradle.properties 文件中添加 android.useDeprecatedNdk=true。
如需监听消息请参考 XGPushBaseReceiver 接口或 Demo（在 SDK 压缩包内，可前往 [SDK 下载](https://console.cloud.tencent.com/tpns/sdkdownload) 页面获取 ）的 MessageReceiver 类。自行继承 XGPushBaseReceiver 并且在配置文件中配置如下内容（请勿在 receiver 里处理耗时操作）：
<receiver android:name="com.tencent.android.xg.cloud.demo.MessageReceiver">
    <intent-filter>
        <!-- 接收消息透传 -->
        <action android:name="com.tencent.android.xg.vip.action.PUSH_MESSAGE" />
        <!-- 监听注册、反注册、设置/删除标签、通知被点击等处理结果 -->
        <action android:name="com.tencent.android.xg.vip.action.FEEDBACK" />
    </intent-filter>
</receiver>
如需兼容 Android P，需要添加使用 Apache HTTP client 库，在 AndroidManifest 的 application 节点内添加以下配置即可。
<uses-library android:name="org.apache.http.legacy" android:required="false"/>

Android Studio 手动集成

前往 SDK 下载 页面获取最新版 SDK，并参考以下步骤将 SDK 导入到您的 Android 工程中。

工程配置

将 SDK 导入到工程的步骤为：
1. 创建或打开 Android 工程。
2. 将移动推送 SDK 目录下的 libs 目录所有 .jar 文件拷贝到工程的 libs（或 lib）目录下。
3. .so 文件是移动推送必须的组件，支持 armeabi、armeabi-v7a、arm64-v8a、mips、mips64、x86、x86_64平台，请根据自己当前 .so 支持的平台添加。
4. 打开 AndroidManifest.xml，添加以下配置（建议参考下载包 Demo 中的 Merged Manifest 修改），其中 “APP的AccessId ” 和 “APP的AccessKey” 替换为 App 对应的 AccessId 和 AccessKey，请确保按照要求配置，否则可能导致服务不能正常使用。

权限配置

移动推送 SDK 正常运行所需要的权限。示例代码如下：
<!-- 【必须】 移动推送 TPNS SDK VIP版本所需权限 -->
<permission
        android:name="应用包名.permission.XGPUSH_RECEIVE"
        android:protectionLevel="signature" />
<uses-permission android:name="应用包名.permission.XGPUSH_RECEIVE" />

<!-- 【必须】 移动推送 TPNS SDK 所需权限 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>

<!-- 【常用】 移动推送 TPNS SDK所需权限 -->
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.RECEIVE_USER_PRESENT" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.GET_TASKS" />
权限
是否必选
说明
android.permission.INTERNET
必选
允许程序访问网络连接，可能产生 GPRS 流量
android.permission.ACCESS_WIFI_STATE
必选
允许程序获取当前 Wi-Fi 接入的状态以及 WLAN 热点的信息
android.permission.ACCESS_NETWORK_STATE
必选
允许程序获取网络信息状态
android.permission.WAKE_LOCK
必选
允许程序在手机屏幕关闭后，后台进程仍然运行
android.permission.SCHEDULE_EXACT_ALARM
必选
允许定时广播
android.permission.VIBRATE
可选
允许应用震动
android.permission.RECEIVE_USER_PRESENT
可选
允许应用可以接收点亮屏幕或解锁广播
android.permission.WRITE_EXTERNAL_STORAGE
可选
允许程序写入外部存储
android.permission.RESTART_PACKAGES
可选
允许程序结束任务
android.permission.GET_TASKS
可选
允许程序获取任务信息

组件和应用信息配置

注意
移动推送 Android SDK 1.1.6.3 及之前版本请参考文档 1.1.6.3 及之前版本组件和应用信息配置 。
<application>
    <activity android:name="com.tencent.android.tpush.TpnsActivity"
            android:theme="@android:style/Theme.Translucent.NoTitleBar"
            android:launchMode="singleInstance"
            android:exported="true">
            <intent-filter>
                <action android:name="${applicationId}.OPEN_TPNS_ACTIVITY" />
                <category android:name="android.intent.category.DEFAULT" />
            </intent-filter>
            <intent-filter>
                <data
                    android:scheme="tpns"
                    android:host="${applicationId}"/>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.BROWSABLE" />
                <category android:name="android.intent.category.DEFAULT" />
            </intent-filter>
            <intent-filter>
                <action android:name="android.intent.action" />
            </intent-filter>
        </activity>

        <activity
            android:name="com.tencent.android.tpush.InnerTpnsActivity"
            android:exported="false"
            android:launchMode="singleInstance"
            android:theme="@android:style/Theme.Translucent.NoTitleBar">
            <intent-filter>
                <action android:name="${applicationId}.OPEN_TPNS_ACTIVITY_V2" />

                <category android:name="android.intent.category.DEFAULT" />
            </intent-filter>
            <intent-filter>
                <data
                    android:host="${applicationId}"
                    android:scheme="stpns" />

                <action android:name="android.intent.action.VIEW" />

                <category android:name="android.intent.category.BROWSABLE" />
                <category android:name="android.intent.category.DEFAULT" />
            </intent-filter>
            <intent-filter>
                <action android:name="android.intent.action" />
            </intent-filter>
        </activity>

        <!-- 【必须】 信鸽receiver广播接收 -->
        <receiver
            android:name="com.tencent.android.tpush.XGPushReceiver"
            android:exported="false"
            android:process=":xg_vip_service">

            <intent-filter android:priority="0x7fffffff">


                <!-- 【必须】 信鸽SDK的内部广播 -->
                <action android:name="com.tencent.android.xg.vip.action.SDK" />
                <action android:name="com.tencent.android.xg.vip.action.INTERNAL_PUSH_MESSAGE" />
                <action android:name="com.tencent.android.xg.vip.action.ACTION_SDK_KEEPALIVE" />
            </intent-filter>

        </receiver>

    <!-- 【必须】移动推送 TPNS service -->
    <service
        android:name="com.tencent.android.tpush.service.XGVipPushService"
        android:exported="false"
        android:process=":xg_vip_service">
    </service>

    <!-- 【必须】通知 service ，android:name 部分改为包名.XGVIP_PUSH_ACTION -->
        <service android:name="com.tencent.android.tpush.rpc.XGRemoteService"
            android:exported="false">
            <intent-filter>
                <!-- 【必须】请修改为当前APP名包.XGVIP_PUSH_ACTION -->
                <action android:name="应用包名.XGVIP_PUSH_ACTION" />
            </intent-filter>
        </service>

    <!-- 【必须】【注意】authorities 修改为包名.XGVIP_PUSH_AUTH -->
    <provider
        android:name="com.tencent.android.tpush.XGPushProvider"
        android:authorities="应用包名.XGVIP_PUSH_AUTH" />

    <!-- 【必须】【注意】authorities 修改为包名.TPUSH_PROVIDER -->
    <provider
        android:name="com.tencent.android.tpush.SettingsContentProvider"
        android:authorities="应用包名.TPUSH_PROVIDER" />

    <!-- 【可选】用于增强保活能力 -->
    <provider
        android:name="com.tencent.android.tpush.XGVipPushKAProvider"
        android:authorities="应用包名.AUTH_XGPUSH_KEEPALIVE"
        android:exported="true" />

    <!-- 【可选】APP实现的Receiver，用于接收消息透传和操作结果的回调，请根据需要添加 -->
    <!-- YOUR_PACKAGE_PATH.CustomPushReceiver需要改为自己的Receiver： -->
    <receiver android:name="应用包名.MessageReceiver"
        android:exported="false">
        <intent-filter>
            <!-- 接收消息透传 -->
            <action android:name="com.tencent.android.xg.vip.action.PUSH_MESSAGE" />
            <!-- 监听注册、反注册、设置/删除标签、通知被点击等处理结果 -->
            <action android:name="com.tencent.android.xg.vip.action.FEEDBACK" />
        </intent-filter>
    </receiver>

    <!-- MQTT START -->
    <service android:exported="false"
            android:process=":xg_vip_service"
            android:name="com.tencent.tpns.mqttchannel.services.MqttService" />

    <provider
            android:exported="false"
            android:name="com.tencent.tpns.baseapi.base.SettingsContentProvider"
            android:authorities="应用包名.XG_SETTINGS_PROVIDER" />

    <!-- MQTT END-->

    <!-- 【必须】 请修改为 APP 的 AccessId，“15”开头的10位数字，中间没空格 -->
    <meta-data
        android:name="XG_V2_ACCESS_ID"
        android:value="APP的AccessId" />
    <!-- 【必须】 请修改为APP的AccessKey，“A”开头的12位字符串，中间没空格 -->
    <meta-data
        android:name="XG_V2_ACCESS_KEY"
        android:value="APP的AccessKey" />

</application>

<!-- 【必须】 移动推送 TPNS SDK 5.0版本所需权限 -->
<permission
    android:name="应用包名.permission.XGPUSH_RECEIVE"
    android:protectionLevel="signature" />
<uses-permission android:name="应用包名.permission.XGPUSH_RECEIVE" />

<!-- 【必须】 移动推送 TPNS SDK所需权限 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>

<!-- 【常用】 移动推送 TPNS SDK所需权限 -->
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.RECEIVE_USER_PRESENT" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
注意
如果您的应用服务接入点为广州，SDK 默认实现该配置。
如果您的应用服务接入点为上海、新加坡或中国香港，请按照下文步骤完成其他服务接入点域名配置，否则会导致注册推送服务失败并返回-502或1008003错误码。 在 AndroidManifest 文件 application 标签内添加以下元数据：
<application>
    // 其他安卓组件
    <meta-data
            android:name="XG_SERVER_SUFFIX"
            android:value="其他服务接入点域名" />
</application>
其他服务接入点域名如下：
上海：tpns.sh.tencent.com
新加坡：tpns.sgp.tencent.com
中国香港：tpns.hk.tencent.com

调试及设备注册

开启 Debug 日志数据

注意：
上线时请设置为 false。
XGPushConfig.enableDebug(this,true);

Token 注册

在需要启动推送服务的地方调用推送服务注册接口：
注意
建议仅在 App 的主进程内调用注册接口。
XGPushManager.registerPush(this, new XGIOperateCallback() {
    @Override
    public void onSuccess(Object data, int flag) {
        //token在设备卸载重装的时候有可能会变
        Log.d("TPush", "注册成功，设备token为：" + data);
    }

    @Override
    public void onFail(Object data, int errCode, String msg) {
        Log.d("TPush", "注册失败，错误码：" + errCode + ",错误信息：" + msg);
    }
});
过滤 "TPush" 注册成功的日志如下：
TPNS register push success with token : 6ed8af8d7b18049d9fed116a9db9c71ab44d5565

关闭日志打印

调用 XGPushConfig.enableDebug(context, false) 关闭 SDK debug 日志开关时，SDK 默认仍会打印部分日常运行日志（包含移动推送 Token）。
您可以通过在 Application.onCreate 内调用如下方法，来关闭这些日常运行日志在控制台的输出打印：
new XGPushConfig.Build(context).setLogLevel(Log.ERROR);

代码混淆

如果您的项目中使用 proguard 等工具，已做代码混淆，请保留以下选项，否则将导致移动推送服务不可用：
-keep public class * extends android.app.Service
-keep public class * extends android.content.BroadcastReceiver
-keep class com.tencent.android.tpush.** {*;}
-keep class com.tencent.tpns.baseapi.** {*;} 
-keep class com.tencent.tpns.mqttchannel.** {*;}
-keep class com.tencent.tpns.dataacquisition.** {*;}

-keep class com.tencent.bigdata.baseapi.** {*;}   // 1.2.0.1 及以上版本不需要此条配置
-keep class com.tencent.bigdata.mqttchannel.** {*;}  // 1.2.0.1 及以上版本不需要此条配置
注意
如果移动推送 SDK 被包含在 App 的公共 SDK 里，即使公共 SDK 有增加配置混淆规则，主工程 App 也必须要同时增加配置混淆规则。

高级配置（可选）

关闭联合保活

如需关闭联合保活功能，请在应用初始化的时候，例如 Application 或 LauncherActivity 的 onCreate 中调用如下接口，并传递 false 值：
注意
仅 1.1.6.0 之后版本支持关闭联合保活功能，1.1.6.0 之前版本移动推送默认开启联合保活能力，且不可关闭。
1.2.6.0 起默认关闭联合保活功能，可不再调用此接口。在 SDK 1.3.4.0 及以上的版本关联启动功能已下线。
XGPushConfig.enablePullUpOtherApp(Context context, boolean pullUp);
若您使用 gradle 自动集成方式，请在自身应用的 AndroidManifest.xml 文件 <application> 标签下配置如下结点，其中 xxx 为任意自定义名称；如果使用手动集成方式，请修改如下节点属性：
<!-- 在自身应用的AndroidManifest.xml文件中添加如下结点，其中 xxx 为任意自定义名称: -->     
<!-- 关闭与 TPNS 应用的联合保活功能，请配置 -->
<provider
         android:name="com.tencent.android.tpush.XGPushProvider"
         tools:replace="android:authorities"
         android:authorities="应用包名.xxx.XGVIP_PUSH_AUTH"
         android:exported="false" />
若控制台有以下日志打印，则表明联合保活功能已经关闭：I/TPush: [ServiceUtil] disable pull up other app。

获取移动推送 Token 交互建议

建议您完成 SDK 集成后，在 App 的关于、意见反馈等比较不常用的 UI 中，通过手势或者其他方式显示移动推送 Token，控制台和 Restful API 推送需要根据移动推送 Token 进行 Token 推送，后续问题排查也需要根据移动推送 Token 进行定位。 示例代码如下：
//获取 Token
XGPushConfig.getToken(getApplicationContext());




获取移动推送运行日志交互建议

SDK 提供日志上报接口。如用户在应用上线后遇到推送相关问题，可以通过引导用户操作触发此接口，上传 SDK 运行日志并获取回调返回的日志文件下载地址，方便问题排查。详情参见 日志上报接口。
示例代码如下：
XGPushManager.uploadLogFile(context, new HttpRequestCallback() {
    @Override
    public void onSuccess(String result) {
        Log.d("TPush", "上传成功，文件地址：" + result);
    }
        @Override
    public void onFailure(int errCode, String errMsg) {
        Log.d("TPush", "上传失败，错误码：" + errCode + ",错误信息：" + errMsg);
    }
});

隐私协议声明建议

您可在申请 App 权限使用时，使用以下内容声明授权的用途：
我们使用 腾讯云移动推送 TPNS 用于实现产品信息的推送，在您授权我们“访问网络连接”和“访问网络状态”权限后，表示您同意 腾讯 SDK 隐私协议。您可以通过关闭终端设备中的通知选项来拒绝接受此 SDK 推送服务。
其中上述声明授权的两个链接如下：
腾讯云移动推送：https://cloud.tencent.com/product/tpns
腾讯 SDK 隐私协议：https://cloud.tencent.com/document/product/548/50955
中国站