目录

获取和注销Token

获取Push Token

[h2]场景介绍

Token是每台设备上每个应用的唯一标识,应用调用getToken方法向Push服务端请求Token,当getToken方法返回为空时,Token可通过onNewToken方法返回,因此您必须实现onNewToken方法。您也可以通过SDK的自动初始化能力来自动获取Token。获取到Token后需要将Token上报到您自己的应用服务器。后续您可以调用下行消息API,根据Token来推送消息。

Token与华为帐号不相关,仅与您的App ID相关,因此切换华为帐号后Token不会变化。建议您直接使用推送服务提供的帐号校验功能来开发帐号相关功能,无需通过Token来判断。

Token一般情况不会变化,仅下列场景Token会发生变化。因此,禁止频繁申请Token,尤其严禁常驻应用定期频繁申请Token。

推送服务为了提升安全性,在2020年11月更新了Token的编码规则,用户只要升级了新版的推送服务应用,当您的应用被卸载重装后,重新打开时申请到的Token即为最新的编码格式。

[h2]注意事项

[h2]开发步骤

建议在应用启动后首个Activity的onCreate方法中调用getToken方法。

  1. 调用getToken方法获取Push Token。

    • 不建议在子进程中申请Push Token。
    • 如果存在多处调用getToken方法的场景,请确保各处入参“appId”的值一致。
    • 调用getToken方法一定要增加异常捕获处理且获取Push Token后一定要做判空处理。
    • HmsInstanceId类及其提供的方法请参见HmsInstanceId。
    “Java”
    private void getToken() {
        // 创建一个新线程
        new Thread() {
            @Override
            public void run() {
                try {
                    // 从agconnect-services.json文件中读取APP_ID
                    String appId = "your APP_ID";
    
                    // 输入token标识"HCM"
                    String tokenScope = "HCM";
                    String token = HmsInstanceId.getInstance(MainActivity.this).getToken(appId, tokenScope);
                    Log.i(TAG, "get token success");
                    
                    // 判断token是否为空
                    if(!TextUtils.isEmpty(token)) {
                        sendRegTokenToServer(token);
                    }
                } catch (ApiException e) {
                    Log.e(TAG, "get token failed, " + e);
                }
            }
        }.start();
    }
    private void sendRegTokenToServer(String token) {
        Log.i(TAG, "sending token to server.");
    }
    “Kotlin”
    private fun getToken() {   
        // 创建一个新线程
        object : Thread() {
            override fun run() {
                try {
                    // 从agconnect-services.json文件中读取APP_ID
                    val appId = "your APP_ID"
                    
                    // 输入token标识"HCM"
                    val tokenScope = "HCM"
                    val token = HmsInstanceId.getInstance(this@MainActivity).getToken(appId, tokenScope)
                    Log.i(TAG, "get token success")
                    
                    // 判断token是否为空
                    if (!TextUtils.isEmpty(token)) { 
                        sendRegTokenToServer(token)
                    }                
                } catch (e: ApiException) { 
                    Log.e(TAG, "get token failed, $e")
                }
            }
        }.start()
    }
    private fun sendRegTokenToServer(token: String) { 
        Log.i(TAG, "sending token to server.")
    }

  2. 在您的service(已继承HmsMessageService)中,覆写onNewToken方法,Push Token发生变化时会在onNewToken方法中返回。

    • 获取Push Token后一定要做判空处理。
    • 如果您集成的Push SDK版本低于5.0.4.302,请及时升级最新Push SDK。
    “Java”
    @Override
    public void onNewToken(String token, Bundle bundle) {         
        // 获取token
        Log.i(TAG, "have received refresh token.");
        
        // 判断token是否为空
        if (!TextUtils.isEmpty(token)) {
            refreshedTokenToServer(token);
        }
    }
    
    private void refreshedTokenToServer(String token) {
        Log.i(TAG, "sending token to server.");
    }
    “Kotlin”
    override fun onNewToken(token: String, bundle: Bundle) {    
        // 获取token
        Log.i(TAG, "have received refresh token.")
        
        // 判断token是否为空
        if (token.isNotEmpty()) { 
            refreshedTokenToServer(token)    
        }
    }
    
    private fun refreshedTokenToServer(token: String) { 
        Log.i(TAG, "sending token to server.")
    }

注销Push Token

[h2]场景介绍

用户拒绝接受您应用的使用协议和隐私声明后,您可以调用deleteToken方法删除Push服务器上对应的Push Token。删除成功后,客户端应用将不再接收到消息。

不建议您调用deleteToken方法删除Push Token,建议您将拒绝应用使用协议和隐私声明用户的Push Token状态设置为无效状态,并控制应用服务端不再向Push Token无效的客户端推送消息,此举可减少应用服务端向Push Kit服务端请求的频率。

  • 禁止频繁注销Push Token。
  • 注销Push Token需要HMS Core(APK)的版本不低于3.0.0。
  • 如果您不希望应用接收消息,可以调用turnOffPush方法关闭通知栏消息。
  • 您应用的使用协议和隐私声明必须包含并遵守《华为推送服务使用协议》和《SDK隐私安全说明》。

[h2]开发步骤

注销Push Token方法示例:

“Java”
private void deleteToken() {
    // 创建一个新线程
    new Thread() {
        @Override
        public void run() {
            try {
                // 从agconnect-services.json文件中读取APP_ID
                String appId = "your APP_ID";
                
                // 输入token标识"HCM"
                String tokenScope = "HCM";

                // 注销Token
                HmsInstanceId.getInstance(context).deleteToken(appId, tokenScope);
                Log.i(TAG, "token deleted successfully");
            } catch (ApiException e) {
                Log.e(TAG, "delete token failed." + e);
            }
        }
    }.start();
}
“Kotlin”
private fun deleteToken() {   
    // 创建一个新线程
    object : Thread() {
        override fun run() {
            try {
                // 从agconnect-services.json文件中读取appId
                val appId = "your APP_ID"
                
                // 输入token标识"HCM"
                val tokenScope = "HCM"

                // 注销token
                HmsInstanceId.getInstance(this@MainActivity).deleteToken(appId, tokenScope)
                Log.i(TAG, "token deleted successfully")
            } catch (e: ApiException) { 
                Log.e(TAG, "delete token failed, $e")
            }
        }
    }.start()
}

自动初始化

Push SDK 4.0版本开始提供了自动生成AAID和获取Push Token的能力。配置本能力后,不需要显式的调用getToken申请Push Token,Push Token以onNewToken回调的方式返回。设置自动初始化的方式如下:

  • 若应用存在使用协议和隐私声明需要用户手动同意,请使用“方式二”进行自动初始化。因为方式一在应用启动时会自动生成AAID并申请Token,即在用户同意使用协议和隐私声明前就触发了自动初始化,不满足个人数据保护规范。
  • 用户同意后调用setAutoInitEnabled方法启用自动初始化。
  • 如果终端设备应用本地“shared_prefs”目录下的文件中保存了对应key(push_kit_auto_init_enabled)的配置信息,Push SDK会直接从中读取信息并判断是否启动了自动初始化。如果应用本地文件中没有保存对应key的配置信息,Push SDK才会从<meta-data>元数据中读取信息。