SDK API

统一推送服务标准接口

统一推送服务（Unified Push Service，简称 UPS）技术标准，旨在为国内的消息推送服务建立统一的标准，为终端用户提供更好的手机使用体验，为应用开发者更好的解决消息推送需求。

从 JPush 3.5.8 版本开始，新增 cn.jpush.android.ups.JPushUPSManager 类，该类提供符合 UPS 标准的接口。

注册接口

注 1：该接口与 JPushInterface.init 接口不建议混用，可直接使用该接口代替 JPushInterface.init 接口。

注 2：manifest 中配置的 appkey 与该接口传入 appkey 建议保持一致，如不一致则以 manifest 中配置的接口为准。

注 3：如果 manifest 中 appkey 配置为空，则以该接口传入的 appkey 为准。

接口定义

           public static void registerToken (Context context, String appID,String appKey, String appSecret, UPSRegisterCallBack callback);

        

参数说明

• context: 应用上下文
• appId: 在极光官网注册应用时生成的 APPKEY
• appKey: 填 null 即可
• appSecret: 填空即可
• callback: 该接口的结果回调，状态码为 0 则说明调用成功，其它值均为失败

使用说明

• 开发者如果主动调用了 registerToken 方法或者其它带 context 参数的方法，都会完成SDK注册，并开启JPush推送服务
• 考虑 APP 上线合规，开发者必须在 APP 用户同意了隐私政策，并且开发者确定为App用户开始提供推送服务后，再调用注册接口使用极光服务
• 关于 APP 隐私政策建议和说明，具体可以参考 如何草拟合规的隐私政策。

反注册接口

注：调用此接口后，会停用所有 Push SDK 提供的功能。需通过 registerToken 接口或者重新安装应用才可恢复。

接口定义

           public static void unRegisterToken (Context context, UPSUnRegisterCallBack callback);

        

参数说明

• context: 应用上下文
• callback：反注册结果。状态码为 0 则说明调用成功，其它值均为失败

停止推送服务

调用了本 API 后，JPush 推送服务完全被停止。具体表现为：

• 收不到推送消息
• 极光推送所有的其他 API 调用都无效，需要调用 cn.jpush.android.ups.JPushUPSManager.turnOnPush 恢复。

接口定义

           public static void turnOffPush (Context context, UPSTurnCallBack callback);

        

参数说明

• context: 应用上下文
• callback：关闭服务结果。状态码为 0 则说明调用成功，其它值均为失败

恢复推送服务

调用了此 API 后，极光推送完全恢复正常工作。

接口定义

           public static void turnOnPush (Context context, UPSTurnCallBack callback);

        

参数说明

• context: 应用上下文
• callback：恢复服务结果。状态码为 0 则说明调用成功，其它值均为失败

设置调试模式 API

功能说明

注：该接口需在 init 接口之前调用，避免出现部分日志没打印的情况。多进程情况下建议在自定义的 Application 中 onCreate 中调用。

接口定义

          public static void setDebugMode(boolean debug);

        

参数说明

• debug 为 true 则会打印 debug 级别的日志，false 则只会打印 warning 级别以上的日志

开启推送业务功能 API

功能说明

极光推送服务，调用了本 API 后，开启JPush 推送服务，将会开始收集上报SDK业务功能所必要的用户个人信息。建议在自定义的 Application 中的 onCreate 中调用。 该 API 支持动态设置极光 AppKey 与各厂商 AppId。 注：如使用该接口配置 AppKey 进行推送业务启用，则 build.gradle 文件中 JPUSH_APPKEY 则不需再配置，即 JPUSH_APPKEY : ""。

接口定义

          public static void init(Context context, JPushConfig config); 

        

参数说明

• context 应用的 ApplicationContext

• config 配置对象，具体参考 JPushConfig 类的说明。

接口使用说明

• 开发者如果主动调用了 init 方法或者其它带 context 参数的方法，都会开启JPush推送服务。
• 考虑 APP 上线合规，开发者必须在APP用户同意了隐私政策，并且开发者确定为App用户开始提供推送服务后，再调用启用推送业务功能接口来使用极光服务。
• 关于 APP 隐私政策建议和说明，具体可以参考 如何草拟合规的隐私政策。

代码示例

          
boolean isPrivacyReady; // app根据是否已弹窗获取隐私授权来赋值
if(!isPrivacyReady){
    //用户同意隐私政策前，不要调用任何极光API接口
}else{
    //App用户同意了隐私政策授权，并且开发者确定要开启推送业务功能后调用
    JPushInterface.init()
}

        

停止与恢复推送服务 API

支持的版本

开始支持的版本：JPush Android SDK v1.3.3

功能说明

JPush SDK 提供的推送服务是默认开启的。

开发者 App 可以通过调用停止推送服务 API 来停止极光推送服务。当又需要使用极光推送服务时，则必须要调用恢复推送服务 API。

停止推送服务

调用了本 API 后，JPush 推送服务完全被停止。具体表现为：

• 极光推送所有的其他 API 调用都无效，不能通过 JPushInterface.init 恢复，需要调用 resumePush 恢复。

接口定义

          public static void stopPush(Context context);

        

参数说明

• context 应用的 ApplicationContext

恢复推送服务

恢复推送服务。

调用了此 API 后，极光推送完全恢复正常工作。

接口定义

          public static void resumePush(Context context);

        

参数说明

          context 应用的 ApplicationContext

        

检查推送是否被停止

• JPush Android SDK v1.5.2 以上版本支持。

接口定义

          public static boolean isPushStopped(Context context);

        

参数说明

• context 应用的 ApplicationContext

代码示例

以下代码来自于 JPush Android Example。

          public class MainActivity extends InstrumentedActivity implements OnClickListener {
    private Button mStopPush;
    private Button mResumePush;
     
    @Override
    public void onCreate(Bundle savedInstanceState) {super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
        initView();}
     
    // 初始化按钮
    private void initView() {mStopPush = (Button)findViewById(R.id.stopPush);
        mStopPush.setOnClickListener(this);
         
        mResumePush = (Button)findViewById(R.id.resumePush);
        mResumePush.setOnClickListener(this);
    }
 
    @Override
    public void onClick(View v) {switch (v.getId()) {
 
        // 点击停止按钮后，极光推送服务会被停止掉
        case R.id.stopPush:
            JPushInterface.stopPush(getApplicationContext());
            break;
 
        // 点击恢复按钮后，极光推送服务会恢复正常工作
        case R.id.resumePush:
            JPushInterface.resumePush(getApplicationContext());
            break;
        }
    }
}

        

申请必须权限接口（ Android 6.0 及以上）

支持的版本

开始支持的版本：JPush Android SDK v4.9.0

功能说明

在 Android 6.0 及以上的系统上，需要去请求JPush SDK 必须用到的权限。具体如下：

          "android.permission.POST_NOTIFICATIONS"

        

实现方法

接口定义

          public static void requestRequiredPermission(Activity activity);

        

参数说明

• activity 当前应用的 Activity 的上下文。

申请可选权限接口（ Android 6.0 及以上）

支持的版本

开始支持的版本：JPush Android SDK v2.1.0

功能说明

在 Android 6.0 及以上的系统上，需要去请求一些用到的权限，JPush SDK 用到的一些需要请求如下权限，因为需要这些权限使统计更加精准，功能更加丰富，建议开发者调用。

          "android.permission.READ_PHONE_STATE"
"android.permission.WRITE_EXTERNAL_STORAGE"
"android.permission.READ_EXTERNAL_STORAGE"
"android.permission.ACCESS_FINE_LOCATION"

        

实现方法

接口定义

          public static void requestPermission(Context context);

        

参数说明

• context 当前应用的 Activity 的上下文

标签操作回调

tag 增删查改的操作会在此方法中回调结果。

支持的版本

开始支持的版本：JPush Android SDK v3.0.7

接口定义

          public void onTagOperatorResult(Context context, JPushMessage jPushMessage);

        

参数定义

• jPushMessage
  • tag 相关操作返回的消息结果体，具体参考 JPushMessage 类的说明。

查询标签绑定状态回调

Method - onCheckTagOperatorResult

查询某个 tag 与当前用户的绑定状态的操作会在此方法中回调结果。

接口定义

          public void onCheckTagOperatorResult(Context context, JPushMessage jPushMessage);

        

参数定义

• jPushMessage
  • check tag 与当前用户绑定状态的操作返回的消息结果体，具体参考 JPushMessage 类的说明。

别名操作回调

alias 相关的操作会在此方法中回调结果。

方法定义

          public void onAliasOperatorResult(Context context, JPushMessage jPushMessage);

        

参数定义

• jPushMessage
  • alias 相关操作返回的消息结果体，具体参考 JPushMessage 类的说明。

设置手机号码回调

设置手机号码会在此方法中回调结果。

支持的版本

开始支持的版本：JPush Android SDK v3.1.1

方法定义

           public void onMobileNumberOperatorResult(Context context, JPushMessage jPushMessage)

        

参数定义

• context
  • 应用的 Application Context。
• jPushMessage
  • 设置手机号码返回的消息结果体，具体参考 JPushMessage 类的说明。

自定义消息回调

同时是应用内提醒回调。

支持的版本

开始支持的版本：JPush Android SDK v3.3.0
说明： 如果需要在旧版本的 Receiver 接收 cn.jpush.android.intent.MESSAGE_RECEIVED 广播
可以不重写此方法，或者重写此方法且调用 super.onMessage
如果重写此方法，没有调用 super，则不会发送广播到旧版本 Receiver

方法定义

           public void onMessage(Context context, CustomMessage customMessage)

        

参数定义

• context
  • 应用的 Application Context。
• CustomMessage
  • 接收自定义消息内容

收到通知回调

支持的版本

开始支持的版本：JPush Android SDK v3.3.0
说明： 如果需要在旧版本的 Receiver 接收 cn.jpush.android.intent.NOTIFICATION_RECEIVED 广播
可以不重写此方法，或者重写此方法且调用 super.onNotifyMessageArrived
如果重写此方法，没有调用 super，则不会发送广播到旧版本 Receiver

方法定义

          public void onNotifyMessageArrived(Context context, NotificationMessage message)

        

参数定义

• context
  • 应用的 Application Context。
• NotificationMessage
  • 接收到的通知内容

点击通知回调

支持的版本

开始支持的版本：JPush Android SDK v3.3.0
说明： 如果需要在旧版本的 Receiver 接收 cn.jpush.android.intent.NOTIFICATION_OPENED 广播
可以不重写此方法，或者重写此方法且调用 super.onNotifyMessageOpened
如果重写此方法，没有调用 super，则不会发送广播到旧版本 Receiver

方法定义

          public void onNotifyMessageOpened(Context context, NotificationMessage message)

        

参数定义

• context
  • 应用的 Application Context。
• NotificationMessage
  • 点击的通知内容

清除通知回调

支持的版本

开始支持的版本：JPush Android SDK v3.3.0

说明:

1. 同时删除多条通知，可能不会多次触发清除通知的回调

2. 只有用户手动清除才有回调，调接口清除不会有回调

方法定义

          public void onNotifyMessageDismiss(Context context, NotificationMessage message)

        

参数定义

• context
  • 应用的 Application Context。
• NotificationMessage
  • 清除的通知内容

通知未展示回调

支持的版本

开始支持的版本：JPush Android SDK v3.5.8

说明:

1.3.5.8 之后支持推送时指定前台不展示功能，当通知未展示时，会回调该接口

方法定义

          public void onNotifyMessageUnShow(Context context, NotificationMessage message)

        

参数定义

• context
  • 应用的 Application Context。
• NotificationMessage
  • 未展示的通知内容

注册成功回调

支持的版本

开始支持的版本：JPush Android SDK v3.3.0

方法定义

          public void onRegister(Context context, String registrationId)

        

参数定义

• context
  • 应用的 Application Context。
• registrationId
  • 注册 id

长连接状态回调

支持的版本

开始支持的版本：JPush Android SDK v3.3.0

方法定义

          public void onConnected(Context context, boolean isConnected)

        

参数定义

• context
  • 应用的 Application Context。
• isConnected
  • 长连接状态

交互事件回调

支持的版本

开始支持的版本：JPush Android SDK v3.3.0

方法定义

          public void onCommandResult(Context context, CmdMessage cmdMessage)

        

参数定义

• context

  • 应用的 Application Context。

• CmdMessage

  • 交互事件回调信息。

通知的 MultiAction 回调

支持的版本

开始支持的版本：JPush Android SDK v3.3.2
说明： 如果需要在旧版本的 Receiver 接收 cn.jpush.android.intent.NOTIFICATION_CLICK_ACTION 广播
可以不重写此方法，或者重写此方法且调用 super.onMultiActionClicked
如果重写此方法，没有调用 super，则不会发送广播到旧版本 Receiver

方法定义

           public void onMultiActionClicked(Context context,Intent intent)

        

参数定义

• context
  • 应用的 Application Context。
• intent
  • 点击后触发的 Intent

说明：注意这个方法里面禁止再调 super.onMultiActionClicked, 因为会导致逻辑混乱

通知开关状态回调

支持的版本

开始支持的版本：JPush Android SDK v3.5.0
说明：

该方法会在以下情况触发时回调。

1.sdk 每次启动后都会检查通知开关状态并通过该方法回调给开发者。 2.当 sdk 检查到通知状态变更时会通过该方法回调给开发者。

方法定义

           public void onNotificationSettingsCheck(Context context,boolean isOn,int source)

        

参数定义

• context
  • 应用的 Application Context。
• isOn
  • 通知开关状态
• source
  • 触发场景，0 为 sdk 启动，1 为检测到通知开关状态变更

说明: sdk 内部检测通知开关状态的方法因系统差异，在少部分机型上可能存在兼容问题(判断不准确)。

拉取围栏列表回调

支持的版本

开始支持的版本：JPush Android SDK v4.0.7

方法定义

          public void onGeofenceReceived(Context context, String geofences)

        

参数定义

• context
  • 应用的 Application Context。
• geofences
  • 地理围栏列表，返回围栏列表为空时，表示当前状态无围栏业务。

围栏数组

透传请求后台返回的围栏 json 数组

一个围栏数组示例：

          [
  {
    "geofenceid": "a4e6cec303",
    "name": "回调围栏 3",
    "center": {
      "lon": "113.87500970263449",
      "lat": "22.777723585199613"
    },
    "radius": 1000,
    "status": "in",
    "repeat": true,
    "repeat_week_num": 0,
    "repeat_day_num": 0,
    "repeat_time": 0,
    "expiration": 1635581786,
    "type": 2, //2 标识回调类型
    "create_time": 1600330718
  },
  {
    "geofenceid": "26349557cd",
    "name": "回调类型",
    "center": {
      "lon": "113.90311563111466",
      "lat": "22.55477581705612"
    },
    "radius": 350,
    "status": "in",
    "repeat": true,
    "repeat_week_num": 0,
    "repeat_day_num": 0,
    "repeat_time": 0,
    "expiration": 1632992234,
    "type": 2,
    "create_time": 1600074007
  }
]

        

触发围栏回调

支持的版本

开始支持的版本：JPush Android SDK v4.0.7

方法定义

          public void onGeofenceRegion(Context context, String geofence, double longitude, double latitude)

        

参数定义

• context
  • 应用的 Application Context。
• geofence
  • 触发围栏详情
• longitude
  • 触发时经度
• latitude
  • 触发时维度

触发围栏详情

String 触发围栏详情 json，经过 SDK 处理，会增加一些本地状态

一个触发围栏详情示例：

          {
  "op": "add",
  "geofenceid": "5543826e95",
  "name": "gdv22021040802",
  "radius": 1000,
  "status": "inside",
  "repeat": true,
  "repeat_week_num": 10,
  "repeat_day_num": 10,
  "repeat_time": 3600,
  "expiration": 1627766421,
  "type": 2,
  "lon": 113.9544839625204,
  "lat": 22.84907665318461,
  "lastTime": 1617896526398, // 当前触发时间
  "lastTimeWeek": "2021-15", // 自然周
  "weekNum": 3, // 当周触发次数
  "lastTimeDay": "2021-098", // 自然天
  "dayNum": 3, // 当天触发次数
  "lastGeoStatus": "in" // 当前是在圈内圈外
}

        

应用内消息展示回调

应用内消息成功展示，会在此方法中回调结果。

支持的版本

开始支持的版本：JPush Android SDK v5.0.0

接口定义

          public void onInAppMessageShow(Context context, NotificationMessage message);

        

参数定义

• context
  • 应用的 Application Context。
• NotificationMessage
  • 应用内消息展示的内容

应用内消息点击回调

应用内消息被用户点击，会在此方法中回调结果。

支持的版本

开始支持的版本：JPush Android SDK v5.0.0

接口定义

          public void onInAppMessageClick(Context context, NotificationMessage message);

        

参数定义

• context
  • 应用的 Application Context。
• NotificationMessage
  • 应用内消息点击的内容

JPushMessageReceiver 回调类

支持版本

此方式是 3.0.7 版本之后新增的回调方式(5.2.0--5.3.1 之间版本修改为JPushMessageService方式），5.4.0 版本后恢复JPushMessageReceiver方式

功能说明

Class - cn.jpush.android.service.JPushMessageReceiver

1. 新的消息回调方式中相关回调类。
2. 新的 tag 与 alias 操作回调会在开发者定义的该类的子类中触发。
3. 手机号码设置的回调会在开发者定义的该类的子类中触发。
4. 新回调方式与旧的自定义 Receiver 兼容：
   配置了此 Receiver 以后，默认是也会发广播给旧 Receiver 的
   对于 onMessage、onNotifyMessageArrived、onNotifyMessageOpened、onMultiActionClicked
   如果重写了这些方法，则需要调用 super 才会发给旧 Receiver

该类为回调父类，开发者需要继承该类并 在 Manifest 中配置 您对应实现的类，接口操作的结果会在您配置的类中的如下方法中回调。

注意： 该回调类虽然基于 BroadcastReceiver, 但为了加快回调速度，在 sdk 内部会判断进程，当触发进程与组件配置的进程一致时，内部采用 java 对象的回调方式，所以并不会产生 android 组件的生命周期，所以不建议在该类中声明 Handler 属性

JPushMessageService方式：如果想使用Service方式，需要：

• 支持版本区间：5.2.0--5.3.1
• 继承类从：JPushMessageReceiver 修改为 JPushMessageService
• 清单文件中:cn.jpush.android.intent.RECEIVER_MESSAGE-->cn.jpush.android.intent.SERVICE_MESSAGE

消息回调说明（已废弃）

支持的版本

开始的版本：最初。

功能说明

JPush SDK 收到推送，通过广播的方式，转发给开发者 App，这样开发者就可以灵活地进行处理。

这个动作不是必须的。用户有需要才定义 Receiver 类来处理 SDK 过来的广播。

如果不做这个动作，即不写自定义 Receiver，也不在 AndroidManifest.xml 里配置这个 Receiver，则默认的行为是：

• 接收到推送的自定义消息，则没有被处理
• 可以正常收到通知，用户点击打开应用主界面

如使用 JPush Android SDK v3.3.0 及之后版本，通知点击默认行为变更如下：

• 如果重写了 onNotifyMessageOpened 则回调到该方法
• 如果未重写 onNotifyMessageOpened 则回调到配置了 cn.jpush.android.intent.NOTIFICATION_OPENED 广播的 receiver 中
• 不重写 onNotifyMessageOpened 也没有配置 action 则点击无反应

如使用 JPush Android SDK v3.5.0 及之后版本，通知点击默认行为变更如下：

• 不重写 onNotifyMessageOpened 也没有配置 action 点击跳转到首页

如使用 JPush Android SDK v4.6.0 及之后版本，通知点击默认行为变更如下：

• 有通知跳转目标地址时，不再广播 extras 参数，若无通知跳转目标地址，则广播 extras 参数(onNotifyMessageOpened 方法)

接收广播

如果全部类型的广播都接收，则需要在 AndroidManifest.xml 里添加如下的配置信息：

          <receiver
    android:name="Your Receiver"
    android:enabled="true"
    android:exported="false">
    <intent-filter>
        <action android:name="cn.jpush.android.intent.REGISTRATION" />
        <action android:name="cn.jpush.android.intent.MESSAGE_RECEIVED" />
        <action android:name="cn.jpush.android.intent.NOTIFICATION_RECEIVED" />
        <action android:name="cn.jpush.android.intent.NOTIFICATION_OPENED" />
        <action android:name="cn.jpush.android.intent.NOTIFICATION_CLICK_ACTION" />
        <action android:name="cn.jpush.android.intent.CONNECTION" />
        <category android:name="You package Name" />
    </intent-filter>
</receiver>

        

每个 Receiver action 详细解释如下。

Action - JPushInterface.ACTION_REGISTRATION_ID

字符串值

          "cn.jpush.android.intent.REGISTRATION"

        

功能描述

SDK 向 JPush Server 注册所得到的注册 ID。

一般来说，可不处理此广播信息。

要深入地集成极光推送，开发者想要自己保存 App 用户与 JPush 用户关系时，则接受此广播，取得 Registration ID 并保存与 App uid 的关系到开发者自己的应用服务器上。

使用极光推送提供的别名与标签功能，是更加简单轻便的绑定 App 用户与 JPush 用户的方式，请参考文档：别名与标签使用教程。

Intent 参数

• JPushInterface.EXTRA_REGISTRATION_ID

  • SDK 向 JPush Server 注册所得到的注册 全局唯一的 ID ，可以通过此 ID 向对应的客户端发送消息和通知。

    Bundle bundle = intent.getExtras(); String title = bundle.getString(JPushInterface.EXTRA_REGISTRATION_ID);

                Bundle bundle = intent.getExtras();
      String title = bundle.getString(JPushInterface.EXTRA_REGISTRATION_ID);
    
            

    此代码块在浮窗中显示

Action - JPushInterface.ACTION_MESSAGE_RECEIVED

字符串值

          "cn.jpush.android.intent.MESSAGE_RECEIVED"

        

功能描述

收到了自定义消息 Push。

SDK 对自定义消息，只是传递，不会有任何界面上的展示。

如果开发者想推送自定义消息 Push，则需要在 AndroidManifest.xml 里配置此 Receiver action，并且在自己写的 BroadcastReceiver 里接收处理。

Intent 参数

• JPushInterface.EXTRA_TITLE

  • 保存服务器推送下来的消息的标题。

  • 对应 API 消息内容的 title 字段。

    • Portal 推送消息界上不作展示

      Bundle bundle = intent.getExtras(); String title = bundle.getString(JPushInterface.EXTRA_TITLE);

• JPushInterface.EXTRA_MESSAGE

  • 保存服务器推送下来的消息内容。

  • 对应 API 消息内容的 message 字段。

  • 对应 Portal 推送消息界面上的“自定义消息内容”字段。

    Bundle bundle = intent.getExtras(); String message = bundle.getString(JPushInterface.EXTRA_MESSAGE);

              Bundle bundle = intent.getExtras();
    String message = bundle.getString(JPushInterface.EXTRA_MESSAGE);
    
            

    此代码块在浮窗中显示

• JPushInterface.EXTRA_EXTRA

  • 保存服务器推送下来的附加字段。这是个 JSON 字符串。

  • 对应 API 消息内容的 extras 字段。

  • 对应 Portal 推送消息界面上的“可选设置”里的附加字段。

    Bundle bundle = intent.getExtras(); String extras = bundle.getString(JPushInterface.EXTRA_EXTRA);

              Bundle bundle = intent.getExtras();
    String extras = bundle.getString(JPushInterface.EXTRA_EXTRA);
    
            

    此代码块在浮窗中显示

• JPushInterface.EXTRA_MSG_ID

  • JPush Android SDK v1.6.1 以上版本支持。

  • 唯一标识消息的 ID, 可用于上报统计等。

    Bundle bundle = intent.getExtras(); String file = bundle.getString(JPushInterface.EXTRA_MSG_ID);

              Bundle bundle = intent.getExtras();
    String file = bundle.getString(JPushInterface.EXTRA_MSG_ID);
    
            

    此代码块在浮窗中显示

Action - JPushInterface.ACTION_NOTIFICATION_RECEIVED

字符串值

          "cn.jpush.android.intent.NOTIFICATION_RECEIVED"

        

功能描述

收到了通知 Push。

如果通知的内容为空，则在通知栏上不会展示通知。

但是，这个广播 Intent 还是会有。开发者可以取到通知内容外的其他信息。

Intent 参数

• JPushInterface.EXTRA_NOTIFICATION_TITLE

  • 保存服务器推送下来的通知的标题。

  • 对应 API 通知内容的 title 字段。

  • 对应 Portal 推送通知界面上的“通知标题”字段。

    Bundle bundle = intent.getExtras(); String title = bundle.getString(JPushInterface.EXTRA_NOTIFICATION_TITLE);

              Bundle bundle = intent.getExtras();
    String title = bundle.getString(JPushInterface.EXTRA_NOTIFICATION_TITLE);
    
            

    此代码块在浮窗中显示

• JPushInterface.EXTRA_ALERT

  • 保存服务器推送下来的通知内容。

  • 对应 API 通知内容的 alert 字段。

  • 对应 Portal 推送通知界面上的“通知内容”字段。

    Bundle bundle = intent.getExtras(); String content = bundle.getString(JPushInterface.EXTRA_ALERT);

              Bundle bundle = intent.getExtras();
    String content = bundle.getString(JPushInterface.EXTRA_ALERT);
    
            

    此代码块在浮窗中显示

• JPushInterface.EXTRA_EXTRA

  • JPush Android SDK v1.2.9 以上版本支持。

  • 保存服务器推送下来的附加字段。这是个 JSON 字符串。

  • 对应 API 通知内容的 extras 字段。

  • 对应 Portal 推送消息界面上的“可选设置”里的附加字段。

    Bundle bundle = intent.getExtras(); String extras = bundle.getString(JPushInterface.EXTRA_EXTRA);

              Bundle bundle = intent.getExtras();
    String extras = bundle.getString(JPushInterface.EXTRA_EXTRA);
    
            

    此代码块在浮窗中显示

• JPushInterface.EXTRA_NOTIFICATION_ID

  • JPush Android SDK v1.3.5 以上版本支持。

  • 通知栏的 Notification ID，可以用于清除 Notification

  • 如果服务端内容（alert）字段为空，则 Notification ID 为 0

    Bundle bundle = intent.getExtras(); int notificationId = bundle.getInt(JPushInterface.EXTRA_NOTIFICATION_ID);

              Bundle bundle = intent.getExtras();
    int notificationId = bundle.getInt(JPushInterface.EXTRA_NOTIFICATION_ID);
    
            

    此代码块在浮窗中显示

• JPushInterface.EXTRA_RICHPUSH_HTML_PATH

  • JPush Android SDK v1.4.0 以上版本支持。

  • 富媒体通知推送下载的 HTML 的文件路径，用于展现 WebView。

    Bundle bundle = intent.getExtras(); String fileHtml = bundle.getString(JPushInterface.EXTRA_RICHPUSH_HTML_PATH);

              Bundle bundle = intent.getExtras();
    String fileHtml = bundle.getString(JPushInterface.EXTRA_RICHPUSH_HTML_PATH);
    
            

    此代码块在浮窗中显示

• JPushInterface.EXTRA_RICHPUSH_HTML_RES

  • JPush Android SDK v1.4.0 以上版本支持。

  • 富媒体通知推送下载的图片资源的文件名，多个文件名用 “，” 分开。与 “JPushInterface.EXTRA_RICHPUSH_HTML_PATH” 位于同一个路径。

    Bundle bundle = intent.getExtras(); String fileStr = bundle.getString(JPushInterface.EXTRA_RICHPUSH_HTML_RES); String[] fileNames = fileStr.split(",");

              Bundle bundle = intent.getExtras();
    String fileStr = bundle.getString(JPushInterface.EXTRA_RICHPUSH_HTML_RES);
    String[] fileNames = fileStr.split(",");
    
            

    此代码块在浮窗中显示

• JPushInterface.EXTRA_MSG_ID

  • JPush Android SDK v1.6.1 以上版本支持。

  • 唯一标识通知消息的 ID，可用于上报统计等。

    Bundle bundle = intent.getExtras(); String file = bundle.getString(JPushInterface.EXTRA_MSG_ID);

              Bundle bundle = intent.getExtras();
    String file = bundle.getString(JPushInterface.EXTRA_MSG_ID);
    
            

    此代码块在浮窗中显示

• JPushInterface.EXTRA_BIG_TEXT

  • JPush Android SDK v3.0.0 以上版本支持，支持 api 16 以上的 rom。

  • 大文本通知样式中大文本的内容。

    Bundle bundle = intent.getExtras(); String bigText = bundle.getString(JPushInterface.EXTRA_BIG_TEXT);

              Bundle bundle = intent.getExtras();
    String bigText = bundle.getString(JPushInterface.EXTRA_BIG_TEXT);
    
            

    此代码块在浮窗中显示

• JPushInterface.EXTRA_BIG_PIC_PATH

  • JPush Android SDK v3.0.0 以上版本支持，支持 api 16 以上的 rom。

  • 可支持本地图片的路径，或者填网络图片地址。

  • 大图片通知样式中大图片的路径 / 地址。

    Bundle bundle = intent.getExtras(); String bigPicPath = bundle.getString(JPushInterface.EXTRA_BIG_PIC_PATH);

              Bundle bundle = intent.getExtras();
    String bigPicPath = bundle.getString(JPushInterface.EXTRA_BIG_PIC_PATH);
    
            

    此代码块在浮窗中显示

• JPushInterface.EXTRA_INBOX

  • JPush Android SDK v3.0.0 以上版本支持，支持 api 16 以上的 rom。

  • 获取的是一个 JSONObject，json 的每个 key 对应的 value 会被当作文本条目逐条展示。

  • 收件箱通知样式中收件箱的内容。

    Bundle bundle = intent.getExtras(); String inboxJson = bundle.getString(JPushInterface.EXTRA_INBOX);

              Bundle bundle = intent.getExtras();
    String inboxJson = bundle.getString(JPushInterface.EXTRA_INBOX);
    
            

    此代码块在浮窗中显示

• JPushInterface.EXTRA_NOTI_PRIORITY

  • JPush Android SDK v3.0.0 以上版本支持，支持 api 16 以上的 rom。

  • 默认为 0，范围为 -2 ～ 2，其他值将会被忽略而采用默认。

  • 通知的优先级。

    Bundle bundle = intent.getExtras(); String prio = bundle.getString(JPushInterface.EXTRA_NOTI_PRIORITY);

              Bundle bundle = intent.getExtras();
    String prio = bundle.getString(JPushInterface.EXTRA_NOTI_PRIORITY);
    
            

    此代码块在浮窗中显示

• JPushInterface.EXTRA_NOTI_CATEGORY

  • JPush Android SDK v3.0.0 以上版本支持，支持 api 21 以上的 rom。

  • 完全依赖 rom 厂商对每个 category 的处理策略，比如通知栏的排序。

  • 通知分类。

    Bundle bundle = intent.getExtras(); String prio = bundle.getString(JPushInterface.EXTRA_NOTI_CATEGORY);

              Bundle bundle = intent.getExtras();
    String prio = bundle.getString(JPushInterface.EXTRA_NOTI_CATEGORY);
    
            

    此代码块在浮窗中显示

Action - JPushInterface.ACTION_NOTIFICATION_OPENED

字符串值

          "cn.jpush.android.intent.NOTIFICATION_OPENED"

        

功能描述

用户点击了通知。 一般情况下，用户不需要配置此 receiver action。

如果开发者在 AndroidManifest.xml 里未配置此 receiver action，那么，SDK 会默认打开应用程序的主 Activity，相当于用户点击桌面图标的效果。

如果开发者在 AndroidManifest.xml 里配置了此 receiver action，那么，当用户点击通知时，SDK 不会做动作。开发者应该在自己写的 BroadcastReceiver 类里处理，比如打开某 Activity 。

Intent 参数

• JPushInterface.EXTRA_NOTIFICATION_TITLE

  • 保存服务器推送下来的通知的标题。

  • 对应 API 通知内容的 title 字段。

  • 对应 Portal 推送通知界面上的“通知标题”字段。

    Bundle bundle = intent.getExtras(); String title = bundle.getString(JPushInterface.EXTRA_NOTIFICATION_TITLE);

              Bundle bundle = intent.getExtras();
    String title = bundle.getString(JPushInterface.EXTRA_NOTIFICATION_TITLE);
    
            

    此代码块在浮窗中显示

• JPushInterface.EXTRA_ALERT

  • 保存服务器推送下来的通知内容。

  • 对应 API 通知内容的 alert 字段。

  • 对应 Portal 推送通知界面上的“通知内容”字段。

    Bundle bundle = intent.getExtras(); String content = bundle.getString(JPushInterface.EXTRA_ALERT);

              Bundle bundle = intent.getExtras();
    String content = bundle.getString(JPushInterface.EXTRA_ALERT);
    
            

    此代码块在浮窗中显示

• JPushInterface.EXTRA_EXTRA

  • JPush Android SDK v1.2.9 以上版本支持。

  • 保存服务器推送下来的附加字段。这是个 JSON 字符串。

  • 对应 API 消息内容的 extras 字段。

  • 对应 Portal 推送消息界面上的“可选设置”里的附加字段。

    Bundle bundle = intent.getExtras(); String type = bundle.getString(JPushInterface.EXTRA_EXTRA);

              Bundle bundle = intent.getExtras();
    String type = bundle.getString(JPushInterface.EXTRA_EXTRA);
    
            

    此代码块在浮窗中显示

• JPushInterface.EXTRA_NOTIFICATION_ID

  • JPush Android SDK v1.3.5 以上版本支持。

  • 通知栏的 Notification ID，可以用于清除 Notification

    Bundle bundle = intent.getExtras(); int notificationId = bundle.getInt(JPushInterface.EXTRA_NOTIFICATION_ID);

              Bundle bundle = intent.getExtras();
    int notificationId = bundle.getInt(JPushInterface.EXTRA_NOTIFICATION_ID);
    
            

    此代码块在浮窗中显示

• JPushInterface.EXTRA_MSG_ID

  • JPush Android SDK v1.6.1 以上版本支持。

  • 唯一标识调整消息的 ID，可用于上报统计等。

    Bundle bundle = intent.getExtras(); String file = bundle.getString(JPushInterface.EXTRA_MSG_ID);

              Bundle bundle = intent.getExtras();
    String file = bundle.getString(JPushInterface.EXTRA_MSG_ID);
    
            

    此代码块在浮窗中显示

Action - JPushInterface.ACTION_NOTIFICATION_CLICK_ACTION

字符串值

          "cn.jpush.android.intent.NOTIFICATION_CLICK_ACTION"

        

功能描述

用户点击了通知栏中自定义的按钮。（JPush Android SDK v3.0.0 以上版本支持）

使用普通通知的开发者不需要配置此 receiver action。只有开发者使用了 MultiActionsNotificationBuilder 构建携带按钮的通知栏的通知时，可通过该 action 捕获到用户点击通知栏按钮的操作，并自行处理。

Intent 参数

• JPushInterface.EXTRA_NOTIFICATION_ACTION_EXTRA

  • SDK 3.0.0 以上版本支持。

  • 获取通知栏按钮点击事件携带的附加信息。

  • 对应使用 MultiActionsNotificationBuilder.addJPushAction 添加的按钮信息。

    private void setAddActionsStyle() {MultiActionsNotificationBuilder builder = new MultiActionsNotificationBuilder(PushSetActivity.this); builder.addJPushAction(R.drawable.jpush_ic_richpush_actionbar_back, "first", "my_extra1"); builder.addJPushAction(R.drawable.jpush_ic_richpush_actionbar_back, "second", "my_extra2"); builder.addJPushAction(R.drawable.jpush_ic_richpush_actionbar_back, "third", "my_extra3"); JPushInterface.setPushNotificationBuilder(10, builder); Toast.makeText(PushSetActivity.this, "AddActions Builder - 10", Toast.LENGTH_SHORT).show();}

              private void setAddActionsStyle() {MultiActionsNotificationBuilder builder = new MultiActionsNotificationBuilder(PushSetActivity.this);
            builder.addJPushAction(R.drawable.jpush_ic_richpush_actionbar_back, "first", "my_extra1");
            builder.addJPushAction(R.drawable.jpush_ic_richpush_actionbar_back, "second", "my_extra2");
            builder.addJPushAction(R.drawable.jpush_ic_richpush_actionbar_back, "third", "my_extra3");
            JPushInterface.setPushNotificationBuilder(10, builder);
    
            Toast.makeText(PushSetActivity.this, "AddActions Builder - 10", Toast.LENGTH_SHORT).show();}
    
            

    此代码块在浮窗中显示

  • 获取到对应的附加信息，确定是哪个按钮后自行处理。

    else if (JPushInterface.ACTION_NOTIFICATION_CLICK_ACTION.equals(intent.getAction())){Log.d(TAG, "[MyReceiver] 用户点击了通知栏按钮"); String nActionExtra = intent.getExtras().getString(JPushInterface.EXTRA_NOTIFICATION_ACTION_EXTRA); // 开发者根据不同 Action 携带的 extra 字段来分配不同的动作。 if(nActionExtra==null){Log.d(TAG,"ACTION_NOTIFICATION_CLICK_ACTION nActionExtra is null"); return; } if (nActionExtra.equals("my_extra1")) {Log.d(TAG, "[MyReceiver] 用户点击通知栏按钮一");} else if (nActionExtra.equals("my_extra2")) {Log.d(TAG, "[MyReceiver] 用户点击通知栏按钮二");} else if (nActionExtra.equals("my_extra3")) {Log.d(TAG, "[MyReceiver] 用户点击通知栏按钮三");} else {Log.d(TAG, "[MyReceiver] 用户点击通知栏按钮未定义");} }

              else if (JPushInterface.ACTION_NOTIFICATION_CLICK_ACTION.equals(intent.getAction())){Log.d(TAG, "[MyReceiver] 用户点击了通知栏按钮");
        String nActionExtra = intent.getExtras().getString(JPushInterface.EXTRA_NOTIFICATION_ACTION_EXTRA);
    
        // 开发者根据不同 Action 携带的 extra 字段来分配不同的动作。
        if(nActionExtra==null){Log.d(TAG,"ACTION_NOTIFICATION_CLICK_ACTION nActionExtra is null");
            return;
        }
        if (nActionExtra.equals("my_extra1")) {Log.d(TAG, "[MyReceiver] 用户点击通知栏按钮一");} else if (nActionExtra.equals("my_extra2")) {Log.d(TAG, "[MyReceiver] 用户点击通知栏按钮二");} else if (nActionExtra.equals("my_extra3")) {Log.d(TAG, "[MyReceiver] 用户点击通知栏按钮三");} else {Log.d(TAG, "[MyReceiver] 用户点击通知栏按钮未定义");}
    }
    
            

    此代码块在浮窗中显示

Action - JPushInterface.ACTION_CONNECTION_CHANGE

字符串值

          "cn.jpush.android.intent.CONNECTION"

        

功能描述

JPush 服务的连接状态发生变化。（注：不是指 Android 系统的网络连接状态。）

Intent 参数

• JPushInterface.EXTRA_CONNECTION_CHANGE

  • JPush Android SDK v1.6.3 以上版本支持。

  • 获取当前 JPush 服务的连接状态。

    Bundle bundle = intent.getExtras(); boolean connected = bundle.getBooleanExtra(JPushInterface.EXTRA_CONNECTION_CHANGE, false);

              Bundle bundle = intent.getExtras();
    boolean connected = bundle.getBooleanExtra(JPushInterface.EXTRA_CONNECTION_CHANGE, false);
    
            

    此代码块在浮窗中显示

    ​

开发者自定义 Receiver 代码示例

          public void onReceive(Context context, Intent intent) {Bundle bundle = intent.getExtras();
    Log.d(TAG, "onReceive -" + intent.getAction());

    if (JPushInterface.ACTION_REGISTRATION_ID.equals(intent.getAction())) {String regId = bundle.getString(JPushInterface.EXTRA_REGISTRATION_ID);
        Log.d(TAG, "[MyReceiver] 接收 Registration Id :" + regId);}else if (JPushInterface.ACTION_MESSAGE_RECEIVED.equals(intent.getAction())) {Log.d(TAG, "收到了自定义消息。消息内容是：" + bundle.getString(JPushInterface.EXTRA_MESSAGE));
        // 自定义消息不会展示在通知栏，完全要开发者写代码去处理
    } else if (JPushInterface.ACTION_NOTIFICATION_RECEIVED.equals(intent.getAction())) {Log.d(TAG, "收到了通知");
        // 在这里可以做些统计，或者做些其他工作
    } else if (JPushInterface.ACTION_NOTIFICATION_OPENED.equals(intent.getAction())) {Log.d(TAG, "用户点击打开了通知");
        // 在这里可以自己写代码去定义用户点击后的行为
        Intent i = new Intent(context, TestActivity.class);  // 自定义打开的界面
        i.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        context.startActivity(i);
    } else {Log.d(TAG, "Unhandled intent -" + intent.getAction());
    }
}

        

更多示例代码请参考 Android SDK 压缩包 中的 example 工程。

JPushMessage 结果类（新回调）

支持版本

JPush Android SDK v3.0.7 版本之后新增的回调方式。

功能说明

Class - cn.jpush.android.api.JPushMessage

1. 新的消息回调方式中相关回调的结果类，使用该类对象可获取对应的操作结果。
2. 当前仅仅新的 tag 与 alias 操作回调会涉及到该类。

查询别名

开发者传或查询得到的 alias。

支持的版本

开始支持的版本：JPush Android SDK v3.0.7

方法定义

          public String getAlias();

        

查询标签

开发者传或查询得到的 tags。

支持的版本

开始支持的版本：JPush Android SDK v3.0.7

方法定义

          public Set<String> getTags();

        

获取操作返回码

对应操作的返回码，0 为成功，其他返回码请参考错误码定义。

支持的版本

开始支持的版本：JPush Android SDK v3.0.7

方法定义

          public int getErrorCode();

        

获取 Sequence

开发者调用接口时传入的 sequence，通过该 sequence 开发者可以从开发者自己缓存中获取到对应的操作。

支持的版本

开始支持的版本：JPush Android SDK v3.0.7

方法定义

          public int getSequence();

        

查询标签的绑定状态

开发者想要查询的 tag 与当前用户绑定的状态。

支持的版本

开始支持的版本：JPush Android SDK v3.0.7

方法定义

          public boolean getTagCheckStateResult();

        

查询绑定状态的标签

开发者想要查询绑定状态的 tag。

支持的版本

开始支持的版本：JPush Android SDK v3.0.7

方法定义

          public String getCheckTag();

        

获取手机号码

开发者调用设置接口时传入的手机号码。

支持的版本

开始支持的版本：JPush Android SDK v3.1.1

方法定义

          public String getMobileNumber();

        

NotificationChannel 配置

支持的版本

开始支持的版本：JPush Android SDK v3.3.4

功能说明

Android8.0 以后通知都走 NotificationChannel 了。开发者可以自行定义 NotificationChannel，然后在 API 推送的时候可以指定 channelId 推送； 在 Android8.0 及以上的机型，通知会先查找对应 channelId 的 channel，通知的重要等级、声音、震动、呼吸灯由 channel 决定； 如果没有找到 channelId，或者处于静默时间内，则走默认的极光 channel。

自定义 NotificationChannel 示例

              private void initChannel(){if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {NotificationManager nm = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
            if (nm != null){NotificationChannelGroup notificationChannelGroup = new NotificationChannelGroup("MyGroupId", "自定义通知组");
                nm.createNotificationChannelGroup(notificationChannelGroup);

                NotificationChannel notificationChannel = new NotificationChannel("MyChannelId", "自定义通知", NotificationManager.IMPORTANCE_HIGH);
                notificationChannel.setGroup("MyGroupId");
                notificationChannel.enableLights(true);
                notificationChannel.enableVibration(true);
                notificationChannel.setSound("android.resource:// 包名 /raw/ 铃声文件", null);    // 设置自定义铃声

                nm.createNotificationChannel(notificationChannel);
            }
        }
    }

        

自定义铃声配置

支持的版本

开始支持的版本：JPush Android SDK v3.3.8

功能说明

此功能实现用户收到推送通知时响起自定义铃声。

• 铃声文件需要放置在应用工程的 /res/raw/ 目录下
• 在 portal 端填写自定义铃声的文件名，注意不需要前面的目录，也不需要后缀名
• 注意如果推送指定了 channel_id， 则铃声效果由手机已有的 channel 的铃声效果为准。由于不同机型和厂商通道存在一定兼容问题，因此我们建议开发者创建自定义 channel，在 channel 里配置自定义铃声（如上节示例那样），这样可以有更好的管控。
• 注意如果指定了静默推送时间，则静默时间内收到的通知，即使设置了自定义铃声，实际效果还是没有铃声。

别名与标签 API

新别名与标签接口支持增删改查的功能，从 3.0.7 版本开始支持，老版本别名与标签的接口从 3.0.7 版本开始不再维护。

注意：极光于 2020/03/10 对「别名设置」的上限进行限制，最多允许绑定 10 个设备。如需更高上限，请 联系商务，详情请阅读 公告。

• JPush Android v3.5.8 及以上、JPush iOS v3.3.2 及以上版本将返回错误码：6027。

• JPush Android v3.5.8 以下、JPush iOS v3.3.2 以下版本将会返回错误码：6017。

• 如果您使用的依旧是老版本已经过时别名与标签接口，如 JPushInterface. setAliasAndTags 及 JPushInterface.setAlias 接口，后台检测到设置超出限制，则会通过接口回调错误码 5。

功能说明

          温馨提示，设置标签别名请注意处理 call back 结果，只有设置成功才可以向目标推送，否则服务器 API 会返回 1011 错误。
从 3.0.7 版本开始，别名和标签是异步回调，注意在 Androidmanifest 里面配置自定义广播接收器

        

别名 alias

为安装了应用程序的用户，取个别名来标识。以后给该用户 Push 消息时，就可以用此别名来指定。

每个用户只能指定一个别名。

同一个应用程序内，对不同的用户，建议取不同的别名。这样，尽可能根据别名来唯一确定用户。

系统不限定一个别名只能指定一个用户。如果一个别名被指定到了多个用户，当给指定这个别名发消息时，服务器端 API 会同时给这多个用户发送消息。

举例：在一个用户要登录的游戏中，可能设置别名为 userid。游戏运营时，发现该用户 3 天没有玩游戏了，则根据 userid 调用 服务器端 API 发通知到客户端提醒用户。

注意：极光于 2020/03/10 对「别名设置」的上限进行限制，最多允许绑定 10 个设备。如需更高上限，请 联系商务，详情请阅读 公告。

• JPush Android v3.5.8 及以上、JPush iOS v3.3.2 及以上版本将返回错误码：6027。

• JPush Android v3.5.8 以下、JPush iOS v3.3.2 以下版本将会返回错误码：6017。

标签 tag

为安装了应用程序的用户，打上标签。其目的主要是方便开发者根据标签，来批量下发 Push 消息。

可为每个用户打多个标签。

举例： game, old_page, women

回调说明

新别名 alias 与标签 tag 接口回调触发 cn.jpush.android.service.JPushMessageReceiver，详细的回调方法请参考 新的消息回调方式说明。

筛选有效标签

支持的版本

开始支持的版本：JPush Android SDK v1.5.0

接口的定义

          public static Set<String> filterValidTags(Set<String> tags);

        

接口返回

有效的 tag 集合。

设置别名

调用此 API 来设置别名。

需要理解的是，这个接口是覆盖逻辑，而不是增量逻辑。即新的调用会覆盖之前的设置。

支持的版本

开始支持的版本：JPush Android SDK v3.0.7

接口定义

          public static void setAlias(Context context, int sequence, String alias);

        

参数定义

• sequence

  • 用户自定义的操作序列号，同操作结果一起返回，用来标识一次操作的唯一性，推荐每次都用不同的数字序号。

• alias

  • 每次调用设置有效的别名，覆盖之前的设置。
  • 有效的别名组成：字母（区分大小写）、数字、下划线、汉字、特殊字符 @!#$&*+=.|。
  • 限制：alias 命名长度限制为 40 字节。（判断长度需采用 UTF-8 编码）

结果回调

详见 onAliasOperatorResult 方法。

注意事项

• init 后直接 set 操作有极大可能导致失败，可能会在回调里拿到 6022,6002 等，测试的时候可以做个 7、8 秒的延时，正式业务里一般配合用户注册使用，延时基本上够用
• 当目标 alias 下已经有 10 个设备时，再去尝试绑定可能会报 6002,6022，可以尝试下后台调用我们的 服务器删除接口 清除下全部绑定关系。

删除别名

调用此 API 来删除别名。

支持的版本

开始支持的版本：JPush Android SDK v3.0.7

接口定义

          public static void deleteAlias(Context context,int sequence);

        

参数定义

• sequence
  • 用户自定义的操作序列号，同操作结果一起返回，用来标识一次操作的唯一性。

结果回调

详见 onAliasOperatorResult 方法。

注意事项

• 此接口只能清除当前设备与目标 alias 的绑定关系，如果你想清除目标 alias 与所有设备的绑定关系，请调 服务器删除接口。

查询别名

调用此 API 来查询别名。

支持的版本

开始支持的版本：JPush Android SDK v3.0.7

接口定义

          public static void getAlias(Context context,int sequence);

        

参数定义

• sequence
  • 用户自定义的操作序列号，同操作结果一起返回，用来标识一次操作的唯一性。

结果回调

详见 onAliasOperatorResult 方法。

设置标签

调用此 API 来设置标签。

需要理解的是，这个接口是覆盖逻辑，而不是增量逻辑。即新的调用会覆盖之前的设置。

支持的版本

开始支持的版本：JPush Android SDK v3.0.7

接口定义

          public static void setTags(Context context, int sequence,Set<String> tags);

        

参数定义

• sequence

  • 用户自定义的操作序列号，同操作结果一起返回，用来标识一次操作的唯一性。

• tags

  • 每次调用至少设置一个 tag，覆盖之前的设置，不是新增。
  • 有效的标签组成：字母（区分大小写）、数字、下划线、汉字、特殊字符 @!#$&*+=.|。
  • 限制：每个 tag 命名长度限制为 40 字节，最多支持设置 1000 个 tag，且单次操作总长度不得超过 5000 字节。（判断长度需采用 UTF-8 编码）
    • 单个设备最多支持设置 1000 个 tag。App 全局 tag 数量无限制。

结果回调

详见 onTagOperatorResult 方法。

新增标签

调用此 API 来新增标签。

支持的版本

开始支持的版本：JPush Android SDK v3.0.7

接口定义

          public static void addTags(Context context, int sequence,Set<String> tags);

        

参数定义

• sequence

  • 用户自定义的操作序列号，同操作结果一起返回，用来标识一次操作的唯一性。

• tags

  • 每次调用至少新增一个 tag。
  • 有效的标签组成：字母（区分大小写）、数字、下划线、汉字、特殊字符 @!#$&*+=.|。
  • 限制：每个 tag 命名长度限制为 40 字节，最多支持设置 1000 个 tag，且单次操作总长度不得超过 5000 字节。（判断长度需采用 UTF-8 编码）
    • 单个设备最多支持设置 1000 个 tag。App 全局 tag 数量无限制。

结果回调

详见 onTagOperatorResult 方法。

删除标签

调用此 API 来删除指定标签。

支持的版本

开始支持的版本：JPush Android SDK v3.0.7

接口定义

          public static void deleteTags(Context context, int sequence,Set<String> tags);

        

参数定义

• sequence

  • 用户自定义的操作序列号, 同操作结果一起返回，用来标识一次操作的唯一性。

• tags

  • 每次调用至少删除一个 tag。
  • 有效的标签组成：字母（区分大小写）、数字、下划线、汉字、特殊字符 @!#$&*+=.|。
  • 限制：每个 tag 命名长度限制为 40 字节，最多支持设置 1000 个 tag，且单次操作总长度不得超过 5000 字节。（判断长度需采用 UTF-8 编码）
    • 单个设备最多支持设置 1000 个 tag。App 全局 tag 数量无限制。

结果回调

详见 onTagOperatorResult 方法。

清除所有标签

调用此 API 来清除所有标签。

支持的版本

开始支持的版本：JPush Android SDK v3.0.7

接口定义

          public static void cleanTags(Context context, int sequence);

        

参数定义

• sequence
  • 用户自定义的操作序列号，同操作结果一起返回，用来标识一次操作的唯一性。

结果回调

详见 onTagOperatorResult 方法。

查询所有标签

调用此 API 来查询所有标签。

支持的版本

开始支持的版本：JPush Android SDK v3.0.7

接口定义

          public static void getAllTags(Context context, int sequence);

        

参数定义

• sequence
  • 用户自定义的操作序列号，同操作结果一起返回，用来标识一次操作的唯一性。

结果回调

详见 onTagOperatorResult 方法。

查询指定标签的绑定状态

调用此 API 来查询指定 tag 与当前用户绑定的状态。

支持的版本

开始支持的版本：JPush Android SDK v3.0.7

接口定义

          public static void checkTagBindState(Context context,int sequence,String tag);

        

参数定义

• sequence

  • 用户自定义的操作序列号，同操作结果一起返回，用来标识一次操作的唯一性。

• tag

  • 被查询的 tag

结果回调

详见 onCheckTagOperatorResult 方法。

别名与标签 API(旧)

1.5.0 ～ 3.0.6 版本提供的别名与标签接口都是覆盖的逻辑，从 3.0.7 版本开始不再维护（但仍会继续保留）。建议开发者使用 3.0.7 开始提供的新 tag、alias 接口。

设置别名与标签 (with Callback)

调用此 API 来同时设置别名与标签。

需要理解的是，这个接口是覆盖逻辑，而不是增量逻辑。即新的调用会覆盖之前的设置。

在之前调用过后，如果需要再次改变别名与标签，只需要重新调用此 API 即可。

支持的版本

开始支持的版本：JPush Android SDK v1.5.0

接口定义

          public static void setAliasAndTags(Context context,
                                   String alias,
                                   Set<String> tags,
                                   TagAliasCallback callback);

        

参数定义

• alias

  • null 此次调用不设置此值。（注：不是指的字符串 "null" ）
  • ""（空字符串）表示取消之前的设置。
  • 每次调用设置有效的别名，覆盖之前的设置。
  • 有效的别名组成：字母（区分大小写）、数字、下划线、汉字、特殊字符（2.1.6 支持）@!#$&*+=.|。
  • 限制：alias 命名长度限制为 40 字节。（判断长度需采用 UTF-8 编码）

• tags

  • null 此次调用不设置此值。（注：不是指的字符串 "null" ）
  • 空数组或列表表示取消之前的设置。
  • 每次调用至少设置一个 tag，覆盖之前的设置，不是新增。
  • 有效的标签组成：字母（区分大小写）、数字、下划线、汉字、特殊字符（2.1.6 支持）@!#$&*+=.|。
  • 限制：每个 tag 命名长度限制为 40 字节，最多支持设置 1000 个 tag，且单次操作总长度不得超过 7000 字节。（判断长度需采用 UTF-8 编码）

• callback

  • 在 TagAliasCallback 的 gotResult 方法，返回对应的参数 alias、tags。并返回对应的状态码：0 为成功，其他返回码请参考错误码定义。

设置别名

调用此 API 来设置别名。

需要理解的是，这个接口是覆盖逻辑，而不是增量逻辑。即新的调用会覆盖之前的设置。也就是说一个设备只能有一个别名。

支持的版本

开始支持的版本：JPush Android SDK v1.5.0

接口定义

          public static void setAlias(Context context, String alias, TagAliasCallback callback)

        

参数定义

• alias

  • ""（空字符串）表示取消之前的设置。
  • 每次调用设置有效的别名，覆盖之前的设置。
  • 有效的别名组成：字母（区分大小写）、数字、下划线、汉字、特殊字符（2.1.6 支持）@!#$&*+=.|。
  • 限制：alias 命名长度限制为 40 字节。（判断长度需采用 UTF-8 编码）

• callback

  • 在 TagAliasCallback 的 gotResult 方法，返回对应的参数 alias、tags。并返回对应的状态码：0 为成功，其他返回码请参考错误码定义。

设置标签

调用此 API 来设置标签。

需要理解的是，这个接口是覆盖逻辑，而不是增量逻辑。即新的调用会覆盖之前的设置。

支持的版本

开始支持的版本：JPush Android SDK v1.5.0

接口定义

          public static void setTags(Context context, Set<String> tags, TagAliasCallback callback)

        

参数定义

• tags

  • 空数组或列表表示取消之前的设置。
  • 每次调用至少设置一个 tag，覆盖之前的设置，不是新增。
  • 有效的标签组成：字母（区分大小写）、数字、下划线、汉字、特殊字符（2.1.6 支持）@!#$&*+=.|。
  • 限制：每个 tag 命名长度限制为 40 字节，最多支持设置 1000 个 tag，且单次操作总长度不得超过 7000 字节。（判断长度需采用 UTF-8 编码）
    • 单个设备最多支持设置 1000 个 tag。App 全局 tag 数量无限制。

• callback

  • 在 TagAliasCallback 的 gotResult 方法，返回对应的参数 alias, tags。并返回对应的状态码：0 为成功，其他返回码请参考错误码定义。

设置别名与标签方法的回调类

Class - TagAliasCallback

设置别名与标签方法的回调类，可在 gotResult 方法上得到回调的结果。回调 responseCode = 0，则确认设置成功。

支持的版本

开始支持的版本：JPush Android SDK v1.5.0

接口定义

          public void gotResult(int responseCode, String alias, Set<String> tags);

        

参数定义

• responseCode
  • 0 表示调用成功。
  • 其他返回码请参考错误码定义。
• alias
  • 原设置的别名
• tags
  • 原设置的标签

错误码定义

请跳转至 错误码定义列表

相关文档

• Android SDK 标签与别名 API
• iOS SDK 标签与别名 API

获取 RegistrationID API

支持的版本

开始支持的版本：JPush Android SDK v1.6.0

功能说明

RegistrationID 定义

集成了 JPush SDK 的应用程序在第一次成功注册到 JPush 服务器时，JPush 服务器会给客户端返回一个唯一的该设备的标识 - RegistrationID。JPush SDK 会以广播的形式发送 RegistrationID 到应用程序。

应用程序可以把此 RegistrationID 保存以自己的应用服务器上，然后就可以根据 RegistrationID 来向设备推送消息或者通知。

实现方法

调用此 API 来取得应用程序对应的 RegistrationID。只有当应用程序成功注册到 JPush 的服务器时才返回对应的值，否则返回空字符串。

注：v3.3.0 版本开始，可以在新的回调 (onRegister 方法) 里面监听到 RegistrationID。

支持的版本

开始支持的版本：JPush Android SDK v1.6.0

接口定义

          SDK 初次注册成功后，开发者通过在自定义的 Receiver 里监听 Action - cn.jpush.android.intent.REGISTRATION 来获取对应的 RegistrationID。
注册成功后，也可以通过函数 public static String getRegistrationID(Context context) 获取

        

附加说明

通过 RegistrationID 进行点对点推送

可以通过 RegistrationID 来推送消息和通知，参考文档 Push API v3，设置 Audience 为 RegistrationID 时即可根据 RegistrationID 推送。

注：要使用此功能，客户端 App 一定要集成有 1.6.0 及以上版本的 JPush Android SDK。

设置手机号码 API

支持的版本

开始支持的版本：JPush Android SDK v3.1.1

功能说明

调用此 API 设置手机号码，用于 短信补充功能。该接口会控制调用频率，频率为 10s 之内最多 3 次。

实现方法

接口定义

          public static void setMobileNumber(Context context,int sequence, String mobileNumber);

        

参数定义

• context
  • 应用的 ApplicationContext。
• sequence
  • 用户自定义的操作序列号，同操作结果一起返回，用来标识一次操作的唯一性。
• mobileNumber
  • 手机号码。如果传 null 或空串则为解除号码绑定操作。
  • 限制：只能以 “+” 或者 数字开头；后面的内容只能包含 “-” 和数字。

回调说明

接口回调触发 cn.jpush.android.service.JPushMessageReceiver，详细的回调方法请参考 新的消息回调方式说明。

厂商通道 Token 回调说明

在国内 Android 生态中，推送通道都是由终端与云端之间的长链接来维持，严重依赖于应用进程的存活状态。如今一些手机厂家会在自家 rom 中做系统级别的推送通道，再由系统分发给各个 app，以此提高在自家 rom 上的推送送达率。各个 rom 均提供了不同的回调 token 的接口，JPush SDK 提供了统一的回调接口。

示例代码

          @Override
public void onCommandResult(Context context, CmdMessage cmdMessage) {
    // 注册失败 + 三方厂商注册回调
    Log.e(TAG,"[onCommandResult]"+cmdMessage);
    //cmd 为 10000 时说明为厂商 token 回调
    if(cmdMessage!=null&&cmdMessage.cmd==10000&&cmdMessage.extra!=null){String token = cmdMessage.extra.getString("token");
        int platform = cmdMessage.extra.getInt("platform");
        String deviceName = "unkown";
        switch (platform){
            case 1:
                deviceName = "小米";
                break;
            case 2:
                deviceName = "华为";
                break;
            case 3:
                deviceName = "魅族";
                break;
            case 4:
                deviceName = "OPPO";
                break;
            case 5:
                deviceName = "VIVO";
                break;
            case 6:
                deviceName = "ASUS";
                break;
            case 7:
                deviceName = "荣耀";
                break;                    
            case 8:
                deviceName = "FCM";
                break;
            case 16:
                deviceName = "NIO";
                break;
        }
    Log.e(TAG,"获取到"+deviceName+"的 token:"+token);
    }
}

        

回调时机

在 sdk 绑定 token 成功时回调, 当 sdk 版本存在变更时会再次触发回调。

存在回调时 token 为 null 的情况: 1. 当集成存在问题会回调 null。 2. 因为厂商服务等问题获取不到厂商 token 时。

配置下载渠道 API

功能说明

动态配置 channel（程序包下载渠道），优先级比 AndroidManifest 里配置的高

• channel 指明应用程序包的下载渠道，为方便分渠道统计，具体值由你自行定义，如华为应用市场、小米应用商店等。
• JPush Android SDK v3.1.5 以上版本支持。

接口定义

          public static void setChannel(Context context, String channel);

        

参数说明

• context 应用的 ApplicationContext
• channel 希望配置的 channel（程序包下载渠道），传 null 表示依然使用 AndroidManifest 里配置的 channel

代码示例

          JPushInterface.setChannel(this, "华为应用市场");

        

应用内消息页面获取和切换

页面生命周期监听

应用内消息展示需要依赖页面，因此需要监听页面的生命周期

Activity方式

极光SDK内部会对Activity的生命周期监听，进行动态控制处理，开发者无需特殊处理

Fragment方式

Fragment需要开发者主动调用接口类JPushInterface 以下两个接口进行动态控制

          /**
* 进入Fragment页面，调用该接口
* @param context ApplicationContext
* @param fragmentName Fragment页面完整类名（this.getClass().getCanonicalName()）
*/
public static void onFragmentResume(Context context, String fragmentName)
 
 
/**
* 退出Fragment页面，调用该接口
* @param context
* @param fragmentName Fragment页面完整类名（this.getClass().getCanonicalName()）
*/
public static void onFragmentPause(Context context, String fragmentName)

        

使用说明： 因为 Android 添加 Fragment 方式共有四种，而每种不同的添加方式，需要对Fragment的处理方式也有不一样。下面就针对 Fragment 的四种方式，指定在指定 Fragment 展示 in app 控制方式，分别进行说明。

• add/show/hide方式

  1）在 Fragment的onCreateView 回调函数中调用动态控制接口，并要求传入参数。 @Override public View onCreateView(LayoutInflater inflater, ViewGroup container,Bundle savedInstanceState) { String classname = this.getClass().getCanonicalName(); JPushInterface.onFragmentResumed(MyApplication.gContext, classname); return inflater.inflate(R.layout.black_fragment, container, false); } 2）在 Fragment 的 onHiddenChaned 回调接口中，调用动态控制接口，并按要求传入参数。 @Override public void onHiddenChanged(boolean hidden) { String classname = this.getClass().getCanonicalName(); if(!hidden){//context传application context JPushInterface.onFragmentResumed(MyApplication.gContext, classname); }else{//hide JPushInterface.onFragmentPaused(MyApplication.gContext, classname); } super.onHiddenChanged(hidden); }

            1）在 Fragment的onCreateView 回调函数中调用动态控制接口，并要求传入参数。
  
  @Override
  public View onCreateView(LayoutInflater inflater, ViewGroup container,Bundle savedInstanceState) {
      String classname = this.getClass().getCanonicalName();
      JPushInterface.onFragmentResumed(MyApplication.gContext, classname);
      return inflater.inflate(R.layout.black_fragment, container, false);
  }  
  
  2）在 Fragment 的 onHiddenChaned 回调接口中，调用动态控制接口，并按要求传入参数。
  
  @Override
  public void onHiddenChanged(boolean hidden) {
      String classname = this.getClass().getCanonicalName();
      if(!hidden){//context传application context
          JPushInterface.onFragmentResumed(MyApplication.gContext, classname);
      }else{//hide
          JPushInterface.onFragmentPaused(MyApplication.gContext, classname);  
      } 
      
      super.onHiddenChanged(hidden);
  }  
  
          

  此代码块在浮窗中显示

• ViewPager方式

  1）在 Fragment 的 setUserVisibleHint 回调接口中，调用动态控制接口，并按要求传入参数。 @Override public void setUserVisibleHint(boolean isVisibleToUser) { String classname = this.getClass().getCanonicalName(); if(isVisibleToUser){ //传application context JPushInterface.onFragmentResumed(MyApplication.gContext, classname); }else{//hide JPushInterface.onFragmentPause(MyApplication.gContext, classname); } super.setUserVisibleHint(isVisibleToUser); }

            1）在 Fragment 的 setUserVisibleHint 回调接口中，调用动态控制接口，并按要求传入参数。
  
  @Override
  public void setUserVisibleHint(boolean isVisibleToUser) {
      String classname = this.getClass().getCanonicalName();
      if(isVisibleToUser){
          //传application context
          JPushInterface.onFragmentResumed(MyApplication.gContext, classname);
      }else{//hide
          JPushInterface.onFragmentPause(MyApplication.gContext, classname);  
      } 
      
      super.setUserVisibleHint(isVisibleToUser);
  }    
  
          

  此代码块在浮窗中显示

• replace 方式或 attach/detach 方式

  在添加Fragment内的生命周期回调接口中，调用动态页面配置接口。 @Override public void onResume() {//传application context String classname = this.getClass().getCanonicalName(); JPushInterface.onFragmentResumed(MyApplication.gContext, classname); super.onResume(); } @Override public void onPause() { String classname = this.getClass().getCanonicalName(); JPushInterface.onFragmentPause(MyApplication.gContext, classname); super.onPause(); }

            在添加Fragment内的生命周期回调接口中，调用动态页面配置接口。
  
  @Override
  public void onResume() {//传application context
      String classname = this.getClass().getCanonicalName();
      JPushInterface.onFragmentResumed(MyApplication.gContext, classname);
      super.onResume();
  }
  
  @Override
  public void onPause() {
      String classname = this.getClass().getCanonicalName();
      JPushInterface.onFragmentPause(MyApplication.gContext, classname);  
      super.onPause();
  }
  
          

  此代码块在浮窗中显示

上报通知打开事件

开始版本

• JPush Android SDK v1.6.1

功能说明

• 用于上报用户的通知栏被打开，或者用于上报用户自定义消息被展示等客户端需要统计的事件。

接口定义

          public static void reportNotificationOpened(Context context, String msgId)

        

参数说明

• context：应用的 ApplicationContext
• msgId：推送每一条消息和通知对应的唯一 ID。（ msgId 来源于发送消息和通知的 Extra 字段 JPushInterface.EXTRA_MSG_ID，参考 接收推送消息 Receiver ）

代码示例

             JPushInterface.reportNotificationOpened(context,bundle.getString(JPushInterface.EXTRA_MSG_ID));

        

扩展业务相关设置

可选个人信息设置

调用此 API 来配置可选个人信息采集

支持的版本

建议使用版本：JPush Android SDK v5.3.1，需要配合JCore Android SDK v4.6.0及以上版本

接口定义

          JPushInterface.setCollectControl(Context context,JPushCollectControl control);

        

参数定义

• context

  • 应用上下文

• JPushCollectControl

  • 采集控制项配置类

JPushCollectControl 控制类

IMEI采集开关

          public Build imei(boolean enable)
    

        

方法说明

配置IMEI信息采集开关，默认为true，false-不允许采集

IMSI采集开关

          public Build imsi(boolean enable)
    

        

方法说明

配置IMSI信息采集开关，默认为true，false-不允许采集

MAC采集开关

          public Build mac(boolean enable)
    

        

方法说明

配置MAC信息采集开关，默认为true，false-不允许采集

SSID采集开关

          public Build ssid(boolean enable)
    

        

方法说明

配置SSID信息采集开关，默认为true，false-不允许采集

BSSID采集开关

          public Build bssid(boolean enable)
    

        

方法说明

配置BSSID信息采集开关，默认为true，false-不允许采集

基站信息采集开关

          public Build cell(boolean enable)
    

        

方法说明

配置基站信息采集开关，默认为true，false-不允许采集

WIFI列表信息采集开关

          public Build wifi(boolean enable)
    

        

方法说明

配置WIFI列表信息采集开关，默认为true，false-不允许采集

          完整示例：
public class MyApplication extends Application {
    @Override
    public void onCreate() {
    JPushCollectControl.Builder builder=new JPushCollectControl.Builder();
    builder.mac(false);
    JPushInterface.setCollectControl(this,builder.build());
    JPushInterface.init(this);
    }
}

        

扩展业务功能设置

调用此 API 来配置扩展业务功能

支持的版本

建议使用版本：JPush Android SDK v5.3.0，需要配合JCore Android SDK v4.6.0及以上版本

用户分群推送

          JPushInterface.setSmartPushEnable(Context context,boolean isSmartPushEnable);

        

参数定义

• context

  • 应用上下文

• isSmartPushEnable

  • 用户分群推送开关，默认为true，false-代表关闭

地理围栏推送

          JPushInterface.setGeofenceEnable(Context context,boolean isGeoPushEnable);
 

        

参数定义

• context

  • 应用上下文

• isGeoPushEnable

  • 地理围栏推送开关，默认为true，false-代表关闭

注意

JPushInterface.setLbsEnable(Context context,boolean isGeoPushEnable) 从5.4.0版本开始废弃

应用自启动

          JCollectionAuth.enableAutoWakeup(Context context,boolean isAutoWakeupEnable);

        

参数定义

• context

  • 应用上下文

• isAutoWakeupEnable

  • 应用自启动开关，默认为true，false-代表关闭

链路调节器

          JPushInterface.setLinkMergeEnable(Context context,boolean isLinkMergeEnable);

        

参数定义

• context

  • 应用上下文

• isLinkMergeEnable

  • 链路调节器开关，默认为true，false-代表关闭

应用活跃时长统计

          JCollectionAuth.enableAppTerminate(Context context,boolean enable);

        

参数定义

• context

  • 应用上下文

• enable

  • 应用活跃时长统计开关，默认为true，false-代表关闭

通知开关 API

通知开启状态

支持的版本

开始支持的版本：JPush Android SDK v3.5.0

功能说明

• 检查当前应用的通知开关是否开启

接口定义

          public static int isNotificationEnabled(Context context)

        

参数说明

• context 是应用的 ApplicationContext
• 返回结果：1 表示开启，0 表示关闭，-1 表示检测失败

跳转至应用通知设置页

支持的版本

开始支持的版本：JPush Android SDK v3.5.0

功能说明

• 跳转手机的应用通知设置页，可由用户操作开启通知开关

接口定义

          public static void goToAppNotificationSettings(Context context)

        

参数说明

• context 是应用的 ApplicationContext

设置是否开启省电模式

支持的版本

开始支持的版本：JPush Android SDK v3.0.9

功能说明

JPush SDK 开启和关闭省电模式，默认为关闭。

实现方法

接口定义

          public static void setPowerSaveMode(Context context,boolean enable);

        

参数说明

• context 当前应用的 Activity 的上下文
• enable 是否需要开启或关闭，true 为开启，false 为关闭

通知栏样式定制 API

支持的版本

开始支持的版本：最初

功能说明

大多数情况下，开发者不需要调用这里的定制通知栏 API 来自定义通知栏样式，只需要使用 SDK 默认的即可。

如果您想：

• 改变 Notification 里的铃声、震动、显示与消失行为
• 自定义通知栏显示样式
• 不同的 Push 通知，Notification 样式不同

则请使用本通知栏定制 API 提供的能力。

教程与代码示例

请参考文档：自定义通知栏样式教程

设置默认通知栏样式构建类

          public static void setDefaultPushNotificationBuilder(DefaultPushNotificationBuilder builder)

        

当用户需要定制默认的通知栏样式时，则可调用此方法。

极光 Push SDK 提供了 3 个用于定制通知栏样式的构建类：

• BasicPushNotificationBuilder
  • Basic 用于定制 Android Notification 里的 defaults / flags / icon 等基础样式（行为）
• CustomPushNotificationBuilder
  • 继承 Basic 进一步让开发者定制 Notification Layout
• MultiActionsNotificationBuilder
  • 继承 DefaultPushNotificationBuilder 进一步让开发者定制 Notification Layout

如果不调用此方法定制，则极光 Push SDK 默认的通知栏样式是：Android 标准的通知栏提示。

设置某编号的通知栏样式构建类

          public static void setPushNotificationBuilder(Integer notificationBuilderId, BasicPushNotificationBuilder builder)

        

当开发者需要为不同的通知，指定不同的通知栏样式（行为）时，则需要调用此方法设置多个通知栏构建类。

3.0.0 版本新增 MultiActionsNotificationBuilder，即带按钮的通知栏构建类，可通过该 api 设置。

设置时，开发者自己维护 notificationBuilderId 这个编号，下发通知时使用 builder_id指定该编号，从而 Push SDK 会调用开发者应用程序里设置过的指定编号的通知栏构建类，来定制通知栏样式。

设置保留最近通知条数 API

支持的版本

开始支持的版本：JPush Android SDK v1.3.0

功能说明

通过极光推送，推送了很多通知到客户端时，如果用户不去处理，就会有很多保留在那里。

从 JPush Android SDK v1.3.0 版本开始 SDK 增加此功能，限制保留的通知条数。默认为保留最近 5 条通知。

开发者可通过调用此 API 来定义为不同的数量。

实现方法

接口定义

          public static void setLatestNotificationNumber(Context context, int maxNum)

        

参数说明

• context 应用的 ApplicationContext
• maxNum 最多显示的条数

调用说明

本接口可以在 JPushInterface.init 之后任何地方调用。可以调用多次。SDK 使用最后调用的数值。

代码示例

          JPushInterface.setLatestNotificationNumber(context, 3);

        

CrashLog 收集并上报

支持的版本

• JPush Android SDK v2.1.8 及以后版本，默认为开启状态，并增加 stopCrashHandler 接口。

功能说明

SDK 通过 Thread.UncaughtExceptionHandler 捕获程序崩溃日志，并在程序奔溃时实时上报如果实时上报失败则会在程序下次启动时发送到服务器。如需要程序崩溃日志功能可调用此方法。

关闭 CrashLog 上报

接口定义

          public static void stopCrashHandler(Context context)

        

参数说明

• Context 应用的 Applicationcontext

开启 CrashLog 上报

接口定义

          public static void initCrashHandler(Context context);

        

参数说明

• Context 应用的 Applicationcontext

获取推送连接状态

支持的版本

开始支持的版本：JPush Android SDK v1.6.3

功能说明

开发者可以使用此功能获取当前 Push 服务的连接状态

当连接状态发生变化时（连接，断开），会发出一个广播，开发者可以在自定义的 Receiver 监听 cn.jpush.android.intent.CONNECTION 获取变化的状态，也可通过 API 主动获取。

实现方法

功能说明

获取当前连接状态

接口定义

          public static boolean getConnectionState(Context context);

        

参数说明

• context 应用的 ApplicationContext

ACTION cn.jpush.android.intent.CONNECTION

intent 参数

JPushInterface.EXTRA_CONNECTION_CHANGE Push 连接状态变化广播传过来的值

          boolean connected = bundle.getBooleanExtra(JPushInterface.EXTRA_CONNECTION_CHANGE, false);

        

示例代码

在 JPush Demo 的 MyReceiver onReceive 方法添加下面代码：

          else if(JPushInterface.ACTION_CONNECTION_CHANGE.equals(intent.getAction())) {boolean connected = intent.getBooleanExtra(JPushInterface.EXTRA_CONNECTION_CHANGE, false);
            Log.e(TAG, "[MyReceiver]" + intent.getAction()+"connected:"+connected);
        }

        

本地通知 API

支持的版本

开始支持的版本：JPush Android SDK v1.6.4

功能说明

通过极光推送的 SDK，开发者只需要简单调用几个接口，便可以在应用中定时发送本地通知

添加一个本地通知

接口定义

          public static void addLocalNotification(Context context, JPushLocalNotification notification)

        

参数说明

• context 是应用的 ApplicationContext
• notification 是本地通知对象；建议 notificationId 设置为正整数，为 0 或者负数时会导致本地通知无法清除。
• 注意华为分类，需要priority和category配合，只需设置priority，sdk会把priority与importance转换上，对应关系如下：
  • PRIORITY_MIN = -2 对应 IMPORTANCE_MIN = 1;
  • PRIORITY_LOW = -1; 对应 IMPORTANCE_LOW = 2;
  • PRIORITY_DEFAULT = 0; 对应 IMPORTANCE_DEFAULT = 3;
  • PRIORITY_HIGH = 1; 对应 IMPORTANCE_HIGH = 4;
  • PRIORITY_MAX = 2; 对应 IMPORTANCE_MAX = 5;

调用说明

本接口可以在 JPushInterface.init 之后任何地方调用

移除指定的本地通知

接口定义

          public static void removeLocalNotification(Context context, long notificationId)

        

参数说明

• context 是应用的 ApplicationContext
• notificationId 是要移除的本地通知的 ID，注意 notificationId 为 0 或者负数的通知无法移除

调用说明

本接口可以在 JPushInterface.init 之后任何地方调用

移除所有的本地通知

注意 notificationId 为 0 或者负数时通知无法移除.

接口定义

          public static void clearLocalNotifications(Context context)

        

参数说明

• context 是应用的 ApplicationContext

调用说明

本接口可以在 JPushInterface.init 之后任何地方调用

本地通知相关设置

          // 设置本地通知类别，5.2.0 版本开始支持
public void setCategory(String category)

// 设置本地通知优先级
public void setPriority(int priority)

// 设置本地通知样式，5.2.0 版本开始支持

public void setBuilderId(long)

// 设置本地通知的 title

public void setTitle(String paramString)

// 设置本地通知的 content

public void setContent(String paramString)

// 设置额外的数据信息 extras 为 json 字符串

public void setExtras(String extras)

// 设置本地通知的 ID

public void setNotificationId(long notificationId)

// 设置本地通知触发时间

public void setBroadcastTime(long broadCastTime)

public void setBroadcastTime(Date date)

public void setBroadcastTime(int year, int month, int day, int hour, int minute, int second)

        

示例代码

          JPushLocalNotification ln = new JPushLocalNotification();
ln.setBuilderId(0);
ln.setContent("hhh");
ln.setTitle("ln");
ln.setNotificationId(11111111) ;
ln.setBroadcastTime(System.currentTimeMillis() + 1000 * 60 * 10);

//分类处理 5.2.0 版本开始支持
ln.setCategory(Notification.CATEGORY_ALARM);
ln.setPriority(Notification.PRIORITY_DEFAULT);
//PRIORITY与IMPORTANCE 相互转换关系
//PRIORITY_MIN = -2 对应 IMPORTANCE_MIN = 1;
//PRIORITY_LOW = -1; 对应 IMPORTANCE_LOW = 2;
//PRIORITY_DEFAULT = 0; 对应 IMPORTANCE_DEFAULT = 3;
//PRIORITY_HIGH = 1; 对应 IMPORTANCE_HIGH = 4;
// PRIORITY_MAX = 2; 对应 IMPORTANCE_MAX = 5;
//分类处理

Map<String , Object> map = new HashMap<String, Object>() ;
map.put("name", "jpush") ;
map.put("test", "111") ;
JSONObject json = new JSONObject(map) ;
ln.setExtras(json.toString()) ;
JPushInterface.addLocalNotification(getApplicationContext(), ln);

        

地理围栏 API

支持的版本

开始支持的版本：JPush Android SDK v3.1.8

功能说明

JPush SDK 提供地理围栏功能，当设备进入或离开相应的地理区域才触发通知或自定义消息。开发者可以通过此功能对 SDK 提供的地理围栏功能进行设置。

设置地理围栏监控周期

功能说明

设置地理围栏监控周期，最小 3 分钟，最大 1 天。默认为 15 分钟，当距离地理围栏边界小于 1000 米周期自动调整为 3 分钟。设置成功后一直使用设置周期，不会进行调整。

接口定义

           public static void setGeofenceInterval(Context context, long interval)

        

参数说明

• context 是应用的 ApplicationContext
• interval 监控周期，单位是毫秒。

设置允许保存的最大地理围栏个数

功能说明

设置最多允许保存的地理围栏数量，超过最大限制后，如果继续创建先删除最早创建的地理围栏。默认数量为 10 个，允许设置最小 1 个，最大 100 个。

接口定义

          public static void setMaxGeofenceNumber(Context context, int maxNumber)

        

参数说明

• context 是应用的 ApplicationContext
• maxNumber 最多允许保存的地理围栏个数

删除地理围栏

功能说明

删除指定 id 的地理围栏

接口定义

          public static void deleteGeofence(Context context, String geofenceid)

        

参数说明

• context 是应用的 ApplicationContext
• geofenceid 地理围栏的 id

角标 API

支持的版本

开始支持的版本：JPush Android SDK v3.3.6

设置角标数字

功能说明

• 设置角标数字(目前仅支持华为手机)

• 如果需要调用这个接口，还需要在 AndroidManifest.xml 里配置华为指定的权限

  <uses-permission android:name="com.huawei.android.launcher.permission.CHANGE_BADGE"/>

              <uses-permission
        android:name="com.huawei.android.launcher.permission.CHANGE_BADGE"/>
  
          

  此代码块在浮窗中显示

接口定义

          public static void setBadgeNumber(Context context, int num)

        

参数说明

• context 是应用的 ApplicationContext
• num 新的角标数字，传入负数将会修正为 0

清除通知 API

支持的版本

开始支持的版本：JPush Android SDK v1.3.5

功能说明

推送通知到客户端时，由 JPush SDK 展现通知到通知栏上。

此 API 提供清除通知的功能，包括：清除所有 JPush 展现的通知（不包括非 JPush SDK 展现的）；清除指定某个通知。

清除所有通知

接口定义

          public static void clearAllNotifications(Context context);

        

参数说明

• Context context： 应用的 ApplicationContext

清除通知

接口定义

          public static void clearNotificationById(Context context, int notificationId);

        

参数说明

          + Context context：应用的 ApplicationContext
+ int notificationId：通知 ID

        

          此 notificationId 来源于 intent 参数 JPushInterface.EXTRA_NOTIFICATION_ID，可参考文档：接收推送消息 Receiver

        

设置允许推送时间 API

支持的版本

开始的版本：最初

功能说明

默认情况下用户在任何时间都允许推送。即任何时候有推送下来，客户端都会收到，并展示。

开发者可以调用此 API 来设置允许推送的时间。

如果不在该时间段内收到消息，SDK 的处理是：推送到的通知会被扔掉。

           这是一个纯粹客户端的实现，所以与客户端时间是否准确、时区等这些，都没有关系。
 而且该接口仅对通知有效，自定义消息不受影响。

        

实现方法

接口定义

          public static void setPushTime(Context context, Set<Integer> weekDays, int startHour, int endHour)

        

参数说明

• Context context 应用的 ApplicationContext
• Set days 0 表示星期天，1 表示星期一，以此类推。 （ 7 天制，Set 集合里面的 int 范围为 0 到 6 ）
  • set 的值为 null，则任何时间都可以收到通知，set 的 size 为 0，则表示任何时间都收不到通知。
• int startHour 允许推送的开始时间 （ 24 小时制：startHour 的范围为 0 到 23 ）
• int endHour 允许推送的结束时间 （ 24 小时制：endHour 的范围为 0 到 23 ）

代码示例

          Set<Integer> days = new HashSet<Integer>();
days.add(1);
days.add(2);
days.add(3);
days.add(4);
days.add(5);
JPushInterface.setPushTime(getApplicationContext(), days, 10, 23);

        

此代码表示周一到周五、上午 10 点到晚上 23 点，都可以推送。

设置通知静默时间 API

支持的版本

开始支持的版本：JPush Android SDK v1.4.0

功能说明

默认情况下用户在收到推送通知时，客户端可能会有震动，响铃等提示。但用户在睡觉、开会等时间点希望为“免打扰”模式，也是静音时段的概念。

开发者可以调用此 API 来设置静音时段。如果在该时间段内收到消息，则：不会有铃声和震动。

实现方法

接口定义

          public static void setSilenceTime(Context context, int startHour, int startMinute, int endHour, int endMinute)

        

参数说明

• Context context 应用的 ApplicationContext
• int startHour 静音时段的开始时间 - 小时 （ 24 小时制，范围：0~23 ）
• int startMinute 静音时段的开始时间 - 分钟（范围：0~59 ）
• int endHour 静音时段的结束时间 - 小时 （ 24 小时制，范围：0~23 ）
• int endMinute 静音时段的结束时间 - 分钟（范围：0~59 ）

代码示例

          JPushInterface.setSilenceTime(getApplicationContext(), 22, 30, 8, 30);

        

此代码表示晚上 10：30 点到第二天早上 8：30 点为静音时段。