SDK Integration

Last updated: 2020-03-31 14:43:25

PDF

Operation scene

Android SDK is an interface provided to developers by Tencent Mobile push service for clients to push messages. This document provides two ways: automatic integration of AndroidStudio Gradle and manual integration of AndroidStudio.

Operation step

Integration method

AndroidStudio Gradle automatic integration

Before configuring SDK, make sure that you have created an application for the Android platform.

  1. Login Tencent Mobile push console Select configuration Management on the left menu to get the package name, AccessID and AccessKey of the application.
  2. In SDK download Page to get the current version number.
  3. Under the app build.gradle file, configure the following:
android {
    ......
    defaultConfig {

        // The package name registered in the console. Note that the application ID, the current app package name, and the app package name registered in the console must be the same.
        applicationId "your package name"
        ......

        ndk {
            // Choose to add .so files corresponding to the CPU type as needed.
            abiFilters 'armeabi', 'armeabi-v7a', 'arm64-v8a'
            // You can also add 'x86', 'x86_64', 'mips', and 'mips64'.
        }

        manifestPlaceholders = [

            XG_ACCESS_ID:"accessid of the registered app",
            XG_ACCESS_KEY : "accesskey of the registered app",
        ]
        ......
    }
    ......
}

dependencies {
    ......
    //Add the following dependencies:
    implementation 'com.tencent.jg:jg:1.1'
    implementation 'com.tencent.tpns:tpns:[VERSION]-release' //  TPNS push [VERSION] is the current SDK version number. You can view the SDK version number on the SDK download page.

}
  1. For overseas cluster access methods, please refer to the following Overseas cluster access method .
  • For example, the following prompt appears in, Android Studio after adding the above abiFilter configuration:
    NDK integration is deprecated in the current plugin. Consider trying the new experimental plugin . Add android.useDeprecatedNdk=true to the gradle.properties file of the Project root Directory.
  • To listen for messages, please refer to the XGPushBaseReceiver API or the MessageReceiver class of demo. Inherit XGPushBaseReceiver and configure the following in the configuration file (do not handle time-consuming operations in receiver):
    <receiver android:name="com.tencent.android.xg.cloud.demo.MessageReceiver">
            <intent-filter>
                <!-- Receive message passthrough -->
                <action android:name="com.tencent.android.xg.vip.action.PUSH_MESSAGE" />
                <!-- Listen to results of registration, unregistration, tag setting/deletion, and notification clicks -->
                <action android:name="com.tencent.android.xg.vip.action.FEEDBACK" />
            </intent-filter>
        </receiver>
  • To be compatible with Android P, you need to add using the Apache HTTP client library and add the following configuration in the application node of AndroidManifest.
<uses-library android:name="org.apache.http.legacy" android:required="false"/>

Manual integration of Android Studio

Engineering configuration
The steps to import SDK into the project are:

  1. Create or open a Android project (refer to the section on how to create a Android project in the development environment).
  2. Copy all the .jar files of libs Directory under Tencent Mobile push SDK Directory to the project's libs (or lib) Directory.
  3. .so file is a necessary component of Tencent Mobile push. It supports armeabi, armeabi-v7a, arm64-v8a, mips, mips64, x86, x86 and 64 platforms. Please add it according to the platform supported by your current .so.
  4. Open Androidmanifest.xml, to add the following configuration (it is recommended to refer to the Demo modification of the download package), in which YOUR_ACCESS_ID and YOUR_ACCESS_KEY are replaced with AccessId and AccessKey, corresponding to App. Make sure to configure them as required, otherwise the service may not be used properly.

Permission configuration
Tencent Mobile pushes Permission for the normal operation of SDK. Sample code is as follows:

    <!-- **Required** Permissions required by TPNS SDK VIP version-->
    <permission
        android:name="app package name.permission.XGPUSH_RECEIVE"
        android:protectionLevel="signature" />
    <uses-permission android:name="app package name.permission.XGPUSH_RECEIVE" />

    <!-- **Required** Permissions required by 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" />

    <!-- **Common** Permissions required by 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" /> 
Permissions Required Description
Android.permission.INTERNET Necessary Allow the program Access to connect to the network, which may generate GPRS Traffic
Android.permission.ACCESS_WIFI_STATE Necessary Allows the program to obtain the status of the current Wi-Fi access and information about WLAN hotspots
Android.permission.ACCESS_NETWORK_STATE Necessary Allow programs to obtain network information status
Android.permission.WAKE_LOCK Optional Allow the Backend Background process to run after the mobile phone screen is turned off
Android.permission.VIBRATE Optional Allow vibration to be applied
Android.permission.READ_PHONE_STATE Optional Allow Access's mobile phone status to be applied.
Android.permission.RECEIVE_USER_PRESENT Optional Allows applications to receive lighted screens or unlocked broadcasts
Android.permission.WRITE_EXTERNAL_STORAGE Optional Allow programs to write to external storage
Android.permission.RESTART_PACKAGES Optional Allow the program to end job
Android.permission.GET_TASKS Optional Allow programs to obtain job information

Component and application information configuration

<application>
    <!-- Other application configurations -->
    <uses-library android:name="org.apache.http.legacy" android:required="false"/> 
    <!-- **Required** TPNS default notification -->
    <activity
        android:name="com.tencent.android.tpush.XGPushActivity">
        <intent-filter>
            <action android:name="android.intent.action" />
        </intent-filter>
    </activity>

    <!-- **Required** TPNS Receiver broadcast reception-->
    <receiver
        android:name="com.tencent.android.tpush.XGPushReceiver"
        android:process=":xg_vip_service">
        <intent-filter android:priority="0x7fffffff">
            <!-- **Required** TPNS SDK internal broadcast -->
            <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" />
            <!-- **Optional** System broadcast: network switching -->
            <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
            <!-- **Optional** System broadcast: network switching -->
            <action android:name="android.intent.action.USER_PRESENT" />
            <!-- [Optional] Some common system broadcasts for increasing the possibility of TPNS service reactivation. You can also add broadcast customized by the app to launch the service -->
            <action android:name="android.bluetooth.adapter.action.STATE_CHANGED" />
            <action android:name="android.intent.action.ACTION_POWER_CONNECTED" />
            <action android:name="android.intent.action.ACTION_POWER_DISCONNECTED" />
        </intent-filter>
    </receiver>

    <!-- **Required** TPNS service -->
    <service
        android:name="com.tencent.android.tpush.service.XGVipPushService"
        android:persistent="true"
        android:process=":xg_vip_service"></service>

    <!-- **Required** Notification service, android:name should be changed to the current package name -->
        <service android:name="com.tencent.android.tpush.rpc.XGRemoteService"
            android:exported="false">
            <intent-filter>
                <!-- **Required** Modify to the current app package name.XGVIP_PUSH_ACTION -->
                <action android:name="app package name.XGVIP_PUSH_ACTION" />
            </intent-filter>
        </service>

    <!-- **Required** **Note** Modify authorities to package name.XGVIP_PUSH_AUTH -->
    <provider
        android:name="com.tencent.android.tpush.XGPushProvider"
        android:authorities="app package name.XGVIP_PUSH_AUTH" />

    <!-- **Required** **Note** Modify authorities to package name.TPUSH_PROVIDER -->
    <provider
        android:name="com.tencent.android.tpush.SettingsContentProvider"
        android:authorities="app package name.TPUSH_PROVIDER" />

    <!-- **Optional** Used to strengthen the keep-alive capability -->
    <provider
        android:name="com.tencent.android.tpush.XGVipPushKAProvider"
        android:authorities="app package name.AUTH_XGPUSH_KEEPALIVE"
        android:exported="true" />

    <!-- **(Optional)** Receiver implemented by the app, which is used to receive the message pass-through and call back the operation result. Add as needed -->
    <!-- YOUR_PACKAGE_PATH.CustomPushReceiver should be changed to your own receiver: -->
    <receiver android:name="app package name.MessageReceiver">
        <intent-filter>
            <!-- Receive message passthrough -->
            <action android:name="com.tencent.android.xg.vip.action.PUSH_MESSAGE" />
            <!-- Listen to results of registration, unregistration, tag setting/deletion, and notification clicks ->
            <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.bigdata.mqttchannel.services.MqttService" />

    <!--**Note** Modify authorities to package name.XG_SETTINGS_PROVIDER. For example, the package name of demo is com.tencent.android.xg.cloud.demo -->
    <provider
        android:exported="false"
        android:name="com.tencent.bigdata.baseapi.base.SettingsContentProvider"
        android:authorities="app package name.XG_SETTINGS_PROVIDER" />

    <!-- MQTT END-->

    <!-- **Required** Change to the AccessId of your app, which is a 10-digit number beginning with "15" and cannot contain spaces -->
    <meta-data
        android:name="XG_V2_ACCESS_ID"
        android:value="AccessId of APP" />
    <!-- **Required** Change to the AccessKey of your app, which is a 12-character string beginning with "A" and cannot contain spaces -->
    <meta-data
        android:name="XG_V2_ACCESS_KEY"
        android:value="AccessKey of app" />
</application>

<!-- **Required** Permissions required by TPNS SDK version 5.0 -->
<permission
    android:name="app package name.permission.XGPUSH_RECEIVE"
    android:protectionLevel="signature" />
<uses-permission android:name="app package name.permission.XGPUSH_RECEIVE" />

<!-- **Required** Permissions required by 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" />

<!-- **Common** Permissions required by 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" />

Overseas cluster access method

To switch the push cluster to Singapore or Hong Kong, China, please follow the above steps to add the following metadata to the application tag of the Androidanifest file after normal integration:

<application>
        // Other Android components
        <meta-data
            android:name="XG_GUID_SERVER"
            android:value="Overseas domain name/guid/api/GetGuidAndMqttServer" />     

        <meta-data
            android:name="XG_STAT_SERVER"
            android:value="Overseas domain name/log/statistics/push" />     

        <meta-data
            android:name="XG_LOG_SERVER"
            android:value="Overseas domain name/v3/mobile/log/upload" /> 
</application>

Overseas domain names are as follows:
Hong Kong, China: https://api.tpns.hk.tencent.com
Singapore: https://api.tpns.sgp.tencent.com

Audio and video rich media usage (optional)

  1. Under layout Directory of App, Create has a xml file named xg_notification.
  2. Copy the following code to the file:
<?xml version="1.0" encoding="UTF-8"?>
-<RelativeLayout android:layout_height="wrap_content" android:layout_width="match_parent" android:id="@+id/xg_root_view" xmlns:android="http://schemas.android.com/apk/res/android">
<!--Notification background. The id name cannot be changed but others can be changed-->
<ImageView android:layout_height="match_parent" android:layout_width="match_parent" android:id="@+id/xg_notification_bg" android:scaleType="centerCrop"/>
<!--Notification icon. The id name cannot be changed but others can be changed. Required.-->
<ImageView android:layout_height="48dp" android:layout_width="48dp" android:id="@+id/xg_notification_icon" android:scaleType="centerInside" android:layout_marginLeft="5dp" android:layout_centerVertical="true" android:layout_alignParentLeft="true"/>
<!--Notification time. The id name cannot be changed but others can be changed. If the time is not displayed, you can remove this layout-->
<TextView android:layout_height="wrap_content" android:layout_width="wrap_content" android:id="@+id/xg_notification_date" android:textSize="12dp" android:layout_marginRight="5dp" android:layout_marginTop="5dp" android:layout_alignParentRight="true" android:layout_alignParentTop="true"/>
<!--Notification title. The id name cannot be changed but others can be changed. Required.-->
<TextView android:layout_height="wrap_content" android:layout_width="match_parent" android:id="@+id/xg_notification_style_title" android:layout_marginLeft="10dp" android:layout_marginTop="20dp" android:singleLine="true" android:layout_toRightOf="@id/xg_notification_icon" android:layout_toLeftOf="@id/xg_notification_date">
<!--Notification content. The id name cannot be changed but others can be changed. Required.-->
<TextView android:layout_height="wrap_content" android:layout_width="match_parent" android:id="@+id/xg_notification_style_content" android:layout_marginTop="1dp" android:singleLine="true" android:layout_toLeftOf="@id/xg_notification_date" android:layout_alignLeft="@+id/xg_notification_style_title" android:layout_below="@+id/xg_notification_style_title"/>
<!--Playback button for rich media notifications with audio or video. The id name cannot be changed but others can be changed. If audio-visual rich media is not used, remove this layout.-->
<ImageView android:layout_height="25dp" android:layout_width="25dp" android:id="@+id/xg_notification_audio_play" android:layout_alignLeft="@+id/xg_notification_style_title" android:visibility="gone" android:background="@android:drawable/ic_media_play" android:layout_alignParentBottom="true"/>
<!--Stop playback button for rich media notifications with audio or video. The id name cannot be changed but others can be changed. If audio-video rich media is not used, remove this layout.-->
<ImageView android:layout_height="25dp" android:layout_width="25dp" android:id="@+id/xg_notification_audio_stop" android:layout_marginLeft="30dp" android:layout_toRightOf="@+id/xg_notification_audio_play" android:visibility="gone" android:background="@android:drawable/ic_media_pause" android:layout_alignParentBottom="true"/></RelativeLayout>

Debugging and Device registration

Enable Debug log data

Please set it to false when Activate

XGPushConfig.enableDebug(this,true);

Token registration

XGPushManager.registerPush(this, new XGIOperateCallback() {
    @Override
    public void onSuccess(Object data, int flag) {
        // The token may change when the device is uninstalled and then reinstalled
        Log.d("TPush", "The registration is successful, the device token is:" + data);
    }

    @Override
    public void onFail(Object data, int errCode, String msg) {
        Log.d("TPush", "The registration failed, error code: " + errCode + ", error message: " + msg);
    }
});

The logs that filter the successful registration of "TPush" are as follows:

XG register push success with token : 6ed8af8d7b18049d9fed116a9db9c71ab44d5565

Obfuscated code

If you have used tools such as proguard in your project and have done Obfuscated code, please keep the following options, otherwise Tencent Mobile push service will be unavailable.

-keep public class * extends android.app.Service
-keep public class * extends android.content.BroadcastReceiver
-keep class com.tencent.android.tpush.** {*;}
-keep class com.tencent.bigdata.baseapi.** {*;}
-keep class com.tencent.bigdata.mqttchannel.** {*;}
-keep class com.tencent.tpns.dataacquisition.** {*;}

Integration recommendation

Get Token (optional)

It is recommended that after you complete the SDK integration, display the Token, by gestures or other means in the less commonly used UI of App, such as "about" and "feedback". This operation is convenient for us to troubleshoot problems later.
Sample code is as follows:

//Get Token
XGPushConfig.getToken(getApplicationContext());