基本设置相关接口_移动研发平台-阿里云帮助中心

说明

以下接口调用时，如有回调均为异步执行，且回调不能为空。

SDK初始化

初始化推送SDK配置，必须在application的onCreate方法中执行，主进程和channel进程必须都执行到

方法定义

public static void init(Context appContext)
public static void init(PushInitConfig pushInitConfig)

// 初始化配置，针对需要多项配置的情况
public class PushInitConfig {
    public static class Builder {
        // application配置，必填
        public Builder application(Application application)
        // appKey 动态配置，使用manifest配置时 不用设置
        public Builder appKey(String appKey)
        // appSecret 动态配置，使用manifest配置时 不用设置
        public Builder appSecret(String appSecret)
        // 禁用channel进程配置，特殊场景使用，不必须，默认不禁用
        public Builder disableChannelProcess(boolean disableChannelProcess)
        // 禁用channel进程的自启动逻辑，默认禁用
        public Builder disableChannelProcessheartbeat(boolean disableChannelProcessHeartbeat)
        // 定期循环拉起channel进程配置，特殊场景使用，不必须
        public Builder loopStartChannel(boolean enable)
        // 定期循环拉起channel进程间隔配置 单位ms，特殊场景使用，不必须
        public Builder loopInterval(long interval) 
        // 构建初始化配置
        public PushInitConfig build()
    }
}

参数说明

参数	类型	是否必填	说明
context	Context	是	应用上下文（需要ApplicationContext）
appKey	String	否	当没有在manifest中配置appKey时，此处必须填写
appSecret	String	否	当没有在manifest中配置appSecret时，此处必须填写
enableChannelProcess	boolean	否	是否使用静默通道，默认是。静默通道用于应用在后台时接收推送，会采取一些提高存活率的措施，如果只需要应用在前台时接收推送，可以不使用静默通道
pushInitConfig	PushInitConfig	是	替代其他init方法，统一所有参数配置到此类。

代码示例

        
        // 一般情况
        PushInitConfig config = new PushInitConfig.Builder()
                .application(this)
                .build();
        PushServiceFactory.init(config);
        
        // 需要代码动态配置appKey和appSecret
        PushInitConfig config = new PushInitConfig.Builder()
                .application(this)
                .appKey("填入应用的appKey")
                .appSecret("填入应用的appSecret")
                .build();
        PushServiceFactory.init(config);
        
        // 特殊场景 需要禁止channel
        PushInitConfig config = new PushInitConfig.Builder()
                .application(this)
                .disableChannelProcess(SpUtils.disableChannel(applicationContext))
                .build();
        PushServiceFactory.init(config);

        // 特殊场景 需要定时拉起channel
        PushInitConfig config = new PushInitConfig.Builder()
                .application(this)
                .loopStartChannel(true)
                .loopInterval(30 * 1000)
                .build();
        PushServiceFactory.init(config);

SDK注册

注册推送通道，开始接收推送。可以根据需要延迟注册，比如需要用户签署完隐私政策

方法定义

void register(Context context, CommonCallback callback);

参数说明

参数	类型	是否必填	说明
context	Context	是	应用上下文（需要ApplicationContext）
callback	CommonCallback	是	回调，错误码参见错误处理

代码示例

        pushService = PushServiceFactory.getCloudPushService();
        pushService.register(applicationContext, new CommonCallback() {
            @Override
            public void onSuccess(String response) {
                Log.i(TAG, "init cloudchannel success  " + pushService.getDeviceId());
                setConsoleText("init cloudchannel success  " + pushService.getDeviceId());
            }

            @Override
            public void onFailed(String errorCode, String errorMessage) {
                Log.e(TAG, "init cloudchannel failed -- errorcode:" + errorCode + " -- errorMessage:" + errorMessage);
                setConsoleText("init cloudchannel failed -- errorcode:" + errorCode + " -- errorMessage:" + errorMessage);
            }
        });

SDK动态注册（废弃）

支持动态设置AppKey、AppSecret的注册接口，与SDK注册功能相同。

重要

3.2.4版本以后不支持此方法调用。如果要在代码中动态注册AppKey和AppSecret，请使用PushServiceFactory.init()带AppKey和AppSecret的初始化方法

方法定义

void register(Context context, String appKey, String appSecret, CommonCallback callback);

参数说明

参数	类型	是否必填	说明
context	Context	是	应用上下文
appKey	String	是	阿里云推送平台的appKey
appSecret	String	是	阿里云推送平台的appSecret
callback	CommonCallback	是	回调，错误码参见错误处理

代码示例

        pushService = PushServiceFactory.getCloudPushService();
        pushService.register(applicationContext, "xxxxx", "xxxxxx", new CommonCallback() {
            @Override
            public void onSuccess(String response) {
                Log.i(TAG, "init cloudchannel success  " + pushService.getDeviceId());
                setConsoleText("init cloudchannel success  " + pushService.getDeviceId());
            }

            @Override
            public void onFailed(String errorCode, String errorMessage) {
                Log.e(TAG, "init cloudchannel failed -- errorcode:" + errorCode + " -- errorMessage:" + errorMessage);
                setConsoleText("init cloudchannel failed -- errorcode:" + errorCode + " -- errorMessage:" + errorMessage);
            }
        });

获取设备标识

获取设备唯一标识，指定设备推送时需要。

方法定义

String getDeviceId();

代码示例

String deviceId = PushServiceFactory.getCloudPushService().getDeviceId();

设置日志等级

在通道初始化之前设置日志等级，默认等级为CloudPushService.LOG_DEBUG。

方法定义

void setLogLevel(int logLevel);

参数说明

参数

类型

是否必填

说明

logLevel

string

是

设置日志等级，支持以下几种类型：

CloudPushService.LOG_ERROR

CloudPushService.LOG_INFO

CloudPushService.LOG_DEBUG

CloudPushService.LOG_OFF：关闭Log

代码示例

        pushService = PushServiceFactory.getCloudPushService();
        pushService.setLogLevel(CloudPushService.LOG_DEBUG);

打开推送通道

重要

SDK版本V3.0.3及以上版本支持。
用于在程序运行时动态打开推送通道，全量推送场景下，打开推送通道需要24小时生效，其他场景实时生效。

打开推送，推送默认就是打开状态，一般与关闭推送通道配套使用，只有关闭过才需要打开推送

方法定义

void turnOnPushChannel(CommonCallback callback);

参数说明

参数	类型	是否必填	说明
callback	CommonCallback	是	操作成功与否的回调

代码示例

       mPushService = PushServiceFactory.getCloudPushService(); 
       mPushService.turnOnPushChannel(new CommonCallback() {
            @Override
            public void onSuccess(String s) {
                tvConsoleText.append("turn on push channel success\n");
            }

            @Override
            public void onFailed(String errorCode, String errorMsg) {
                tvConsoleText.append("turn on push channel failed." +
                        "errorCode: " + errorCode + ", errorMsg:" + errorMsg + "\n");
            }
        });

关闭推送通道

重要

SDK版本V3.0.3及以上版本支持。
用于在程序运行时动态关闭推送通道，全量推送场景下，关闭推送通道需要24小时生效，其他场景实时生效。

关闭推送，注意此时并不是真正断开推送通道，而是告诉服务这个设备不接收推送了。关闭之后，即使重新初始化SDK也不会打开推送，需要主动调用打开推送，才会重新接收推送

方法定义

void turnOffPushChannel(CommonCallback callback);

参数说明

参数	类型	是否必填	说明
callback	CommonCallback	是	操作成功与否的回调

代码示例

       mPushService = PushServiceFactory.getCloudPushService(); 
       mPushService.turnOffPushChannel(new CommonCallback() {
            @Override
            public void onSuccess(String s) {
                tvConsoleText.append("turn off push channel success\n");
            }

            @Override
            public void onFailed(String errorCode, String errorMsg) {
                tvConsoleText.append("turn off push channel failed." +
                        "errorCode: " + errorCode + ", errorMsg:" + errorMsg + "\n");
            }
        });

查询推送通道状态

重要

SDK版本V3.0.3及以上版本支持。
用于在程序运行时查询当前推送通道状态，如果当前为打开状态，则通过callback.success(String response)回调传入on，反之则传入off。

判断当前推送打开关闭状态

方法定义

void checkPushChannelStatus(CommonCallback callback);

public interface CommonCallback {

    void onSuccess(String response);

    void onFailed(String errorCode, String errorMessage);
}

参数说明

参数	类型	是否必填	说明
callback	CommonCallback	是	查询结果回调，response为on表示推送通道打开，off表示推送通道关闭

示例代码

        mPushService = PushServiceFactory.getCloudPushService(); 
        mPushService.checkPushChannelStatus(new CommonCallback() {
            @Override
            public void onSuccess(String response) {
                if (response.equals("on")) {
                    // 当前是打开状态
                } else {
                    // 当前是关闭状态
                }
            }

            @Override
            public void onFailed(String errorCode, String errorMessage) {
            }
        });

设置消息接收IntentService

重要

SDK版本V3.0.10及以上版本支持。
通过IntentService组件接收消息回调。
设置后消息将通过该组件透出，不再通过MessageReceiver

设置接收推送的服务，服务需要继承AliyunMessageIntentService。默认使用广播的方式接收推送，设置之后会改为使用服务接收推送

方法定义

void setPushIntentService(Class messageIntentService);

参数说明

参数

类型

是否必填

说明

messageIntentService

Class

否

自定义接收消息IntentService的class，继承AliyunMessageIntentService。

null表示使用广播接收推送

代码示例

        mPushService = PushServiceFactory.getCloudPushService(); 
        mPushService.setPushIntentService(MyMessageIntentService.class);

应用内通道控制接口

重要

SDK版本V3.7.4及以上版本支持。
此类接口用于一些需要连接强控制的场景，手机场景不需要

控制接口包括判断应用内通道是否连接、重连、重置、监听连接状态等接口。

监听连接状态接口和判断应用内通道是否连接接口主要用于辅助业务方判断连接的状态。

重连接口用于在业务方发现连接断开一定时间还未重连上时，主动尝试重连。

重置接口用于重置SDK内部的初始化状态，用于在主动重连后，连接也不会恢复时，重置SDK内部状态，然后调用SDK注册接口，重新注册推送通道

接口定义

public interface PushControlService {

    /**
     * 判断是否连接
     *
     * @return
     */
    boolean isConnected();

    /**
     * 监听连接状态
     *
     * @param listener
     */
    void setConnectionChangeListener(ConnectionChangeListener listener);

    /**
     * 在 连接断开的情况下，重试重连
     */
    void reconnect();

    /**
     * 重置 本地数据状态，之后可以重新 注册推送
     */
    void reset();

    public static interface ConnectionChangeListener {
        /**
         * 连接建立成功
         */
        void onConnect();

        /**
         * 连接断开
         * 注意如果要记录断开的具体原因，请一定记录msg信息
         * @param code
         * @param msg
         */
        void onDisconnect(String code, String msg);
    }
}

通过PushServiceFactory获取接口

public class PushServiceFactory {
    public static PushControlService getPushControlService()
}

代码示例

        final PushControlService controlService = PushServiceFactory.getPushControlService();
        controlService.reconnect();

接收SDK日志输出

重要

如果要输出日志到文件或者上传，注意不要包含debug和info级别日志，避免日志量过大，影响应用性能

注册日志接口，用于接收SDK日志信息，排查问题

接口定义

public class AmsLogger {
    public static void addListener(final LoggerListener lisn)
}

通过PushServiceFactory获取接口

public class PushServiceFactory {
    public static PushControlService getPushControlService()
}
public interface LoggerListener {

    public void d(String TAG, String msg, Throwable tr, int flag);

    public void i(String TAG, String msg, Throwable tr, int flag);

    public void w(String TAG, String msg, Throwable tr, int flag);

    public void e(String TAG, String msg, Throwable tr, int flag);

}

代码示例

    public static void registerWarnLog() {
        AmsLogger.addListener(new LoggerListener() {
            @Override
            public void d(String TAG, String msg, Throwable tr, int flag) {

            }

            @Override
            public void i(String TAG, String msg, Throwable tr, int flag) {

            }

            @Override
            public void w(String TAG, String msg, Throwable tr, int flag) {
                // 记录 warn日志
                log.w(TAG, msg, tr);
            }

            @Override
            public void e(String TAG, String msg, Throwable tr, int flag) {
                // 记录 error日志
                log.e(TAG, msg, tr);
            }
        });
    }