极光推送 sdk 集成 全部推送 与别名标签推送

SDK集成步骤

1、导入 SDK 开发包到你自己的应用程序项目

• 解压缩 jpush-sdk_v1.x.y.zip 集成压缩包
• 复制 libs/jpush-sdk-release1.x.y.jar 到工程 libs/ 目录下

• 复制 libs/armeabi/libjpush.so 到工程 libs/armeabi 目录下

  如果您的项目有 libs/armeabi-v7a 这个目录，请把 libjpush.so 也复制一份到这个目录。

2、配置 AndroidManifest.xml

根据 SDK 压缩包里的 AndroidManifest.xml 样例文件，来配置应用程序项目的 AndroidManifest.xml 。

主要步骤为：

1. 复制备注为 "Required" 的部分
2. 将备注为替换包名的部分，替换为当前应用程序的包名
3. 将AppKey替换为在Portal上注册该应用的的Key,例如（9fed5bcb7b9b87413678c407）

权限配置：
<?xml version= "1.0" encoding= "utf-8" ?>
<manifest xmlns:android= "<a href="http://schemas.android.com/apk/res/android" "="" style="outline: none; color: rgb(0, 109, 175); border-top-left-radius: 0px !important; border-top-right-radius: 0px !important; border-bottom-right-radius: 0px !important; border-bottom-left-radius: 0px !important; border: 0px !important; bottom: auto !important; float: none !important; height: auto !important; left: auto !important; line-height: 1.2em !important; margin: 0px !important; overflow: visible !important; padding: 0px !important; position: static !important; right: auto !important; top: auto !important; vertical-align: baseline !important; width: auto !important; box-sizing: content-box !important; font-size: 1em !important; min-height: inherit !important; background: none !important;">http://schemas.android.com/apk/res/android"
    package = "Your Package"
    android:versionCode= "100"
    android:versionName= "1.0.0"
    >

    <!-- Required -->
    <permission android:name= "Your Package.permission.JPUSH_MESSAGE" android:protectionLevel= "signature" />

    <!-- Required -->
    <uses-permission android:name= "You Package.permission.JPUSH_MESSAGE" />
    <uses-permission android:name= "android.permission.RECEIVE_USER_PRESENT" />
    <uses-permission android:name= "android.permission.INTERNET" />
    <uses-permission android:name= "android.permission.WAKE_LOCK" />
    <uses-permission android:name= "android.permission.READ_PHONE_STATE" />
    <uses-permission android:name= "android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name= "android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name= "android.permission.VIBRATE" />
    <uses-permission android:name= "android.permission.MOUNT_UNMOUNT_FILESYSTEMS" />
    <uses-permission android:name= "android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name= "android.permission.WRITE_SETTINGS" /> <!--since 1.6 . 0 -->

    <!-- Optional. Required for location feature -->
    <uses-permission android:name= "android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name= "android.permission.ACCESS_COARSE_UPDATES" />
    <uses-permission android:name= "android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name= "android.permission.CHANGE_WIFI_STATE" />
    <uses-permission android:name= "android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name= "android.permission.ACCESS_LOCATION_EXTRA_COMMANDS" />
    <uses-permission android:name= "android.permission.CHANGE_NETWORK_STATE" />

应用包名及appkey替换：
    <application
        android:icon= "@drawable/ic_launcher"
        android:label= "@string/app_name"
        android:name= "Your Application" >

        <!-- Required -->
        <service
            android:name= "cn.jpush.android.service.PushService"
            android:enabled= "true"
            android:exported= "false" >
            <intent-filter>
                <action android:name= "cn.jpush.android.intent.REGISTER" />
                <action android:name= "cn.jpush.android.intent.REPORT" />
                <action android:name= "cn.jpush.android.intent.PushService" />
                <action android:name= "cn.jpush.android.intent.PUSH_TIME" />
            </intent-filter>
        </service>

        <!-- Required -->
        <receiver
            android:name= "cn.jpush.android.service.PushReceiver"
            android:enabled= "true" >
          <intent-filter android:priority= "1000" > <!--since 1.3 . 5 -->
                <action android:name= "cn.jpush.android.intent.NOTIFICATION_RECEIVED_PROXY" /> <!--since 1.3 . 5 -->
                <category android:name= "Your Package" /> <!--since 1.3 . 5 -->
            </intent-filter> <!--since 1.3 . 5 -->
            <intent-filter>
                <action android:name= "android.intent.action.USER_PRESENT" />
                <action android:name= "android.net.conn.CONNECTIVITY_CHANGE" />
            </intent-filter>
            <intent-filter>
                <action android:name= "android.intent.action.PACKAGE_ADDED" />
                <action android:name= "android.intent.action.PACKAGE_REMOVED" />
                <data android:scheme= "package" />
            </intent-filter>
        </receiver>
     <!-- Required SDK核心功能-->
        <activity
            android:name= "cn.jpush.android.ui.PushActivity"
            android:theme= "@android:style/Theme.Translucent.NoTitleBar"
            android:configChanges= "orientation|keyboardHidden" >
            <intent-filter>
                <action android:name= "cn.jpush.android.ui.PushActivity" />
                <category android:name= "android.intent.category.DEFAULT" />
                <category android:name= "Your Package" />
            </intent-filter>
        </activity>
        <!-- Required SDK核心功能-->
        <service
            android:name= "cn.jpush.android.service.DownloadService"
            android:enabled= "true"
            android:exported= "false" >
        </service>
        <!-- Required SDK核心功能-->
        <receiver android:name= "cn.jpush.android.service.AlarmReceiver" />

        <!-- Required. For publish channel feature -->
        <!-- JPUSH_CHANNEL 是为了方便开发者统计APK分发渠道。-->
        <!-- 例如: -->
        <!-- 发到 Google Play 的APK可以设置为 google-play; -->
        <!-- 发到其他市场的 APK 可以设置为 xxx-market。 -->
        <!-- 目前这个渠道统计功能的报表还未开放。-->
        <meta-data android:name= "JPUSH_CHANNEL" android:value= "developer-default" />
        <!-- Required. AppKey copied from Portal -->
        <meta-data android:name= "JPUSH_APPKEY" android:value= "Your AppKey" />
    </application>
</manifest>

3、添加代码

JPush SDK 提供的 API 接口，都主要集中在 cn.jpush.android.api.JPushInterface 类里。

基础 API 

• init 初始化SDK

public static void init(Context context)

• setDebugMode 设置调试模式

// You can enable debug mode in developing state. You should close debug mode when release.
public static void setDebugMode( boolean debugEnalbed)

添加统计代码

• 参考文档： 统计分析 API

调用示例代码（参考 example 项目）

• init 只需要在应用程序启动时调用一次该 API 即可。
• 以下代码定制一个本应用程序 Application 类。需要在 AndoridManifest.xml 里配置。请参考上面 AndroidManifest.xml 片断，或者 example 项目。

public class ExampleApplication extends Application {
     @Override
     public void onCreate() {
         super .onCreate();
         JPushInterface.setDebugMode( true );
         JPushInterface.init( this );
     }
}

4、测试确认

1. 确认所需的权限都已经添加。如果必须的权限未添加，日志会提示错误。
2. 确认 AppKey（在Portal上生成的）已经正确的写入 Androidmanifest.xml 。
3. 确认在程序启动时候调用了init(context) 接口
4. 确认测试手机（或者模拟器）已成功连入网络
   
   • 客户端调用 init 后不久，如果一切正常，应有登录成功的日志信息
5. 启动应用程序，在 Portal 上向应用程序发送自定义消息或者通知栏提示。详情请参考管理Portal。
   
   • 在几秒内，客户端应可收到下发的通知或者正定义消息

如果 SDK 工作正常，则日志信息会如下图所示：

如图所示，客户端启动分为 4 步：

1. 检查 metadata 的 appKey 和 channel ，如果不存在，则启动失败
2. 初始化 JPush SDK，检查 JNI 等库文件的有效性，如果库文件无效，则启动失败
3. 检查 Androidmanifest.xml，如果有 Required 的权限不存在，则启动失败
4. 连接服务器登录，如果存在网络问题，则登陆失败,或者前面三步有问题，不会启动JPush SDK

别名 alias

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

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

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

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

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

标签 tag

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

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

不同应用程序、不同的用户，可以打同样的标签。

举例： game, old_page,  women

Method - setAliasAndTags (with Callback)

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

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

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

支持的版本

开始支持的版本：1.5.0.

接口定义

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

参数定义

• alias
  
  • null 此次调用不设置此值。（注：不是指的字符串"null"）
  • "" （空字符串）表示取消之前的设置。
  • 每次调用设置有效的别名，覆盖之前的设置。
  • 有效的别名组成：字母（区分大小写）、数字、下划线、汉字。
  • 限制：alias 命名长度限制为 40 字节。（判断长度需采用UTF-8编码）
• tags
  
  • null 此次调用不设置此值。（注：不是指的字符串"null"）
  • 空数组或列表表示取消之前的设置。
  • 每次调用至少设置一个 tag，覆盖之前的设置，不是新增。
  • 有效的标签组成：字母（区分大小写）、数字、下划线、汉字。
  • 限制：每个 tag 命名长度限制为 40 字节，最多支持设置 100 个 tag，但总长度不得超过1K字节。（判断长度需采用UTF-8编码）
    • 单个设备最多支持设置 100 个 tag。App 全局 tag 数量无限制。
• callback
  

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

Method - setAlias

调用此 API 来设置别名。

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

支持的版本

开始支持的版本：1.5.0.

接口定义

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

参数定义

• alias
  
  • "" （空字符串）表示取消之前的设置。
  • 每次调用设置有效的别名，覆盖之前的设置。
  • 有效的别名组成：字母（区分大小写）、数字、下划线、汉字。
  • 限制：alias 命名长度限制为 40 字节。（判断长度需采用UTF-8编码）
• callback
  

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

Method - setTags

调用此 API 来设置标签。

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

使用建议 如果待设置的 alias / tags 是动态的，有可能在调用 setAliasAndTags 时因为 alias / tags 无效而整调用失败。 调用此方法只设置 tags，可以排除可能无效的 alias 对本次调用的影响。

支持的版本

开始支持的版本：1.5.0.

接口定义

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

参数定义

• tags
  
  • 空数组或列表表示取消之前的设置。
  • 每次调用至少设置一个 tag，覆盖之前的设置，不是新增。
  • 有效的标签组成：字母（区分大小写）、数字、下划线、汉字。
  • 限制：每个 tag 命名长度限制为 40 字节，最多支持设置 100 个 tag，但总长度不得超过1K字节。（判断长度需采用UTF-8编码）
    • 单个设备最多支持设置 100 个 tag。App 全局 tag 数量无限制。
• callback
  

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

Method - filterValidTags(Set<String> tags)

使用建议 设置 tags 时，如果其中一个 tag 无效，则整个设置过程失败。 如果 App 的 tags 会在运行过程中动态设置，并且存在对 JPush SDK tag 规定的无效字符，则有可能一个 tag 无效导致这次调用里所有的 tags 更新失败。 这时你可以调用本方法 filterValidTags 来过滤掉无效的 tags，得到有效的 tags，再调用 JPush SDK 的 set tags / alias 方法。

支持的版本

1.5.0

接口定义

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

参数定义

• tags 原 tag 集合。有可能包含无效的 tag。

接口返回

有效的 tag 集合。

Class - TagAliasCallback

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

支持的版本

开始支持的版本：1.5.0

接口定义

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

参数定义

• responseCode

  • 0 表示调用成功。

  • 其他返回码请参考错误码定义。

• alias
  
  • 原设置的别名
• tags
  
  • 原设置的标签

错误码定义

Code	描述	详细解释
6001	无效的设置，tag/alias 不应参数都为 null
6002	设置超时	建议重试
6003	alias 字符串不合法	有效的别名、标签组成：字母（区分大小写）、数字、下划线、汉字。
6004	alias超长。最多 40个字节	中文 UTF-8 是 3 个字节
6005	某一个 tag 字符串不合法	有效的别名、标签组成：字母（区分大小写）、数字、下划线、汉字。
6006	某一个 tag 超长。一个 tag 最多 40个字节	中文 UTF-8 是 3 个字节
6007	tags 数量超出限制。最多 100个	这是一台设备的限制。一个应用全局的标签数量无限制。
6008	tag/alias 超出总长度限制。总长度最多 1K 字节