概述

Android

iOS

REST API

服务端SDK

2. Android SDK 快速集成指南

2.1 说明

  • 本文档是ixintui Android SDK 集成指南,主要用于ixintui Android SDK的接入配置、使用与注意事项。
  • 版本说明:
    • SDK版本:2.1.1
    • 发布日期: 2019-05-23
    • 下载地址:http://www.ixintui.com/?indexactive=2&indexpage=intro
    • 版本说明:
      适配apk引入androidx.appcompat:appcompat:1.0.0-beta01而不引入v4包的情况
      适配targetSdkVersion大于等于26的情况
      删除相应的静态注册广播,将注册的静态广播改成动态注册形式
      在调用register前调用以下代码
import com.ixintui.push.Receiver;

IntentFilter ixintuiFilter = new IntentFilter();
ixintuiFilter.addAction("com.ixintui.action.BROADCAST");
ixintuiFilter.addAction("android.intent.action.BOOT_COMPLETED");
ixintuiFilter.addAction("android.net.conn.CONNECTIVITY_CHANGE");
IntentFilter ixintuiFilterRemove = new IntentFilter();
ixintuiFilterRemove.addAction("android.intent.action.PACKAGE_REMOVED");
ixintuiFilterRemove.addDataScheme("package");
Receiver ixintuiReceiver = new Receiver();
registerReceiver(ixintuiReceiver,ixintuiFilter);
registerReceiver(ixintuiReceiver,ixintuiFilterRemove);

2.2 添加资源文件

  • 解压SDK后添加以下jar包和资源文件:
    • 将/libs目录下ixintui_pushsdk_vx.y.z.jar包放入工程libs目录下。
    • 将/res/layout、/res/values、/res/drawable目录下的文件放入工程对应目录。其中:
    1. /drawable/ixintui_small_icon.png为状态栏图标,用户可自行设计适配并替换,否则默认使用ixintui设计图标(只有48x48px)。
    2. 图标要求只使用alpha图层,不能包括RGB图层(图标不能有颜色,参考默认图标设计)。
    • 将AndroidPushSDK/res/xml目录下的xml放入工程对应目录,如无该目录请新建。并将ixintui_sync.xml文件中的yourpackage修改为应用包名:

      ixintui_sync.xml:
<?xml version="1.0" encoding="utf-8"?>
<sync-adapter xmlns:android="http://schemas.android.com/apk/res/android"
    android:accountType="com.ixintui.push.account"
    android:allowParallelSyncs="true"
    <-- 请将packagename修改为应用包名-->
    android:contentAuthority="yourpackage.provider"
    android:isAlwaysSyncable="true"
    android:supportsUploading="false"
    android:userVisible="true" />

2.3 配置AndroidManifest

2.3.1 Permission权限配置

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
 <uses-permission android:name="android.permission.GET_TASKS" />
 <uses-permission android:name="android.permission.INTERNET" />
 <uses-permission android:name="android.permission.READ_PHONE_STATE" />
 <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
 <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
 <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
 <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.WAKE_LOCK"/>
 <uses-permission android:name="android.permission.REORDER_TASKS" />
 <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
 <uses-permission android:name="android.permission.AUTHENTICATE_ACCOUNTS" />
 <uses-permission android:name="android.permission.READ_SYNC_SETTINGS" />
 <uses-permission android:name="android.permission.WRITE_SYNC_SETTINGS" />
 <uses-permission android:name="android.permission.GET_ACCOUNTS" />
 <uses-permission android:name="com.sec.android.provider.badge.permission.READ" />
 <uses-permission android:name="com.sec.android.provider.badge.permission.WRITE" />
 <uses-permission android:name="com.htc.launcher.permission.READ_SETTINGS" />
 <uses-permission android:name="com.htc.launcher.permission.UPDATE_SHORTCUT" />
 <uses-permission android:name="com.anddoes.launcher.permission.UPDATE_COUNT" />
 <uses-permission android:name="com.majeur.launcher.permission.UPDATE_BADGE" />
 <uses-permission android:name="com.huawei.android.launcher.permission.READ_SETTINGS" />
 <uses-permission android:name="com.huawei.android.launcher.permission.CHANGE_BADGE" />
 <uses-permission android:name="com.huawei.android.launcher.permission.WRITE_SETTINGS" />
 <uses-permission android:name="com.sonyericsson.home.permission.RECEIVE_BADGE" />
 <uses-permission android:name="com.sonyericsson.home.permission.BROADCAST_BADGE" />

2.3.2 application标签内

<!-- 定义接收器,用来接收透传、api结果以及点击事件 -->
<!-- 请把此处设置为您定义的BroadcastReceiver派生类全名 -->
<receiver 
    android:name="yourpackage.PushReceiver">
    <intent-filter>
        <!-- 接收透传消息 -->
        <action android:name="com.ixintui.action.MESSAGE" />
        <!-- 接收register, add tag等反馈消息 -->
        <action android:name="com.ixintui.action.RESULT" />
        <!-- 接收notification click消息 -->
        <action android:name="com.ixintui.action.notification.CLICK" />
    </intent-filter>
</receiver>

<!-- 以下为push使用的活动,服务和接收器,请不要修改这些内容 -->
<activity
    android:name="com.ixintui.push.PushActivity"
    android:theme="@android:style/Theme.Translucent.NoTitleBar"
    android:configChanges="orientation|keyboardHidden" >
    <intent-filter>
        <action android:name="com.ixintui.push.PushActivity" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>
<!-- Rich push 核心功能 since 1.8-->
<activity
    android:name="com.ixintui.push.RichpushActivity"
    android:theme="@android:style/Theme.Translucent">
</activity>
<!-- push服务 -->
<service
    android:name="com.ixintui.push.PushService"
    android:exported="true"
    android:process=":ixintui_service_v1">
    <intent-filter>
        <action android:name="android.content.SyncAdapter" />
    </intent-filter>
    <meta-data
        android:name="android.content.SyncAdapter"
        android:resource="@xml/ixintui_sync" />
</service>
<service android:name="com.ixintui.push.DeamonService">
    <intent-filter>
        <action android:name="android.accounts.AccountAuthenticator" />
    </intent-filter>
    <meta-data
        android:name="android.accounts.AccountAuthenticator"
        android:resource="@xml/ixintui_deamon" />
</service>
<service
    android:name="com.ixintui.push.MediateService"
    android:exported="true" >
</service>
<!-- 推送内部使用的provider -->
<provider
    android:name="com.ixintui.push.Provider"
    android:exported="false"
    android:multiprocess="true"
    <!-- 请把yourpackage替换成您的应用包名 -->
    android:authorities="yourpackage.ixintui.push.provider"/>
<provider
    android:name="com.ixintui.push.SyncProvider"
    <!-- 请把yourpackage替换成您的应用包名 -->
    android:authorities="yourpackage.provider"
    android:exported="false"
    android:syncable="true" />
<!--如果targetSdkVersion大于或者等于26,该静态注册广播无效,需要动态注册广播-->
<receiver android:name="com.ixintui.push.Receiver">
    <intent-filter>
        <action android:name="com.ixintui.action.BROADCAST" />
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.PACKAGE_REMOVED"/>
        <data android:scheme="package" />
    </intent-filter>
    <intent-filter >
        <action android:name="android.intent.action.BOOT_COMPLETED" />
        <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
    </intent-filter>
</receiver>

2.4 添加PushReceiver

  • 开发者下发消息后,应用需要在本地实现一个BroadcastReceiver派生类进行接收,并在接收成功后根据特有的业务场景进行进一步处理。
  • 请确保在AndroidManifest.xml文件中已经注册过该receiver。
/*** 推送消息接收器 ***/
@Override
public void onReceive(Context context, Intent intent) 
{
    String action = intent.getAction();
    // 透传消息
    if (action.equals(SdkConstants.MESSAGE_ACTION)) 
    {
        String msg = intent.getStringExtra(SdkConstants.MESSAGE);
        String extra = intent.getStringExtra(SdkConstants.ADDITION);
        Log.d(TAG, "message received, msg is: " + msg + "extra: " + extra);
        // 处理透传内容
        // ...
    } 
    // SDK API的异步返回结果
    else if (action.equals(SdkConstants.RESULT_ACTION)) 
    {
         // API 名称
         String cmd = intent.getStringExtra(SdkConstants.COMMAND);
         // 返回值,0为成功,否则失败
         int code = intent.getIntExtra(SdkConstants.CODE, 0);
         if (code != 0) 
         {
             // 错误信息
             String error = intent.getStringExtra(SdkConstants.ERROR);
             Log.d(TAG, "command is: " + cmd + " result error: " + error);
        } 
        else 
        {
            Log.d(TAG, "command is: " + cmd + "result OK");
        }
        // 附加结果,比如添加成功的tag, 比如推送是否暂停等
        String extra = intent.getStringExtra(SdkConstants.ADDITION);
        if (extra != null) 
        {
            Log.d(TAG, "result extra: " + extra);
        }       
    }
    // 通知点击事件
    else if (action.equals(SdkConstants.NOTIFICATION_CLICK_ACTION)) 
    {
        String msg = intent.getStringExtra(SdkConstants.MESSAGE);
        Log.d(TAG, "notification click received, msg is: " + msg);
    }            
}

2.5 注册推送服务

  • 该接口是所有其他功能正常使用的基础。在每次应用启动时,必须调用该接口才能保证推送的正常进行。
  • 方法说明:
  1. 请在应用的第一个Activity类(启动的第一个类)的oncreate中添加下面代码。
  2. 或者在应用的appliation派生类的oncreate中添加下面一行代码。
//如果targetSdkVersion大于或者等于26 则需要先动态注册ixintui的广播
import com.ixintui.push.Receiver;

IntentFilter ixintuiFilter = new IntentFilter();
ixintuiFilter.addAction("com.ixintui.action.BROADCAST");
ixintuiFilter.addAction("android.intent.action.BOOT_COMPLETED");
ixintuiFilter.addAction("android.net.conn.CONNECTIVITY_CHANGE");
IntentFilter ixintuiFilterRemove = new IntentFilter();
ixintuiFilterRemove.addAction("android.intent.action.PACKAGE_REMOVED");
ixintuiFilterRemove.addDataScheme("package");
Receiver ixintuiReceiver = new Receiver();
registerReceiver(ixintuiReceiver,ixintuiFilter);
registerReceiver(ixintuiReceiver,ixintuiFilterRemove);

//请一定确保四个参数都有值
//参数appKey为应用从ixintui申请的应用唯一标识符
//参数channel标识应用的分发渠道,用于统计推送信息,
//参数appVersion标识应用版本信息,用于统计推送信息
//参数miAppId小米appId
//参数miAppKey小米appKey
//参数mzAppId魅族appId
//参数mzAppKey魅族appKey
PushSdkApi.register(this, appKey, channel, appVersion);    
//如果您希望在对应设备上使用小米/华为/魅族推送,请使用以下注册接口:
PushSdkApi.register(this, appKey, channel, appVersion, miAppId, miAppKey, mzAppId, mzAppKey);    
  • 初始化(注册)是个异步过程,初始化(注册)成功后,其结果会被Receiver接收, 应用可以获取到一个token来唯一标识本设备。获取方法如下:
String extra = intent.getStringExtra(SdkConstants.ADDITION);
  • 函数无需重复多次调用,否则会在Receiver中重复返回结果token。

2.6 混淆编译配置

  • 如果应用进行混淆编译,需要在混淆的配置文件中加入以下代码,避免SDK被二次混淆编译,才能确保SDK功能正常使用。
  • 如果开发者使用了定制名的SDK,也需要对相应的包名加入类似代码。
-keep class com.ixintui.** {*;} 
-keep public interface com.ixintui.** {*;}
//如不使用华为推送,请配置:
-dontwarn com.ixintui.push.HWPushReceiver

2.7 打包时资源保持的配置

  • 如果应用打包时选择去除资源,使用shrinkResources true进行了资源去除,需要在res/raw/目录加入一个keep.xml,避免SDK所需的layout被去除。其内容如下:
<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@layout/ixintui_*"/>

2.8 API

  • 请参考[Android SDK API](Android SDK API.md)

2.9 注意事项

2.9.1 集成注意事项

  • 如果之前您集成过旧版本推送sdk,请将旧版本的so和jar包等文件删除。
  • 为保证SDK的正常使用,请务必确保不要遗漏文件。
  • V1.9.4版本后要求应用必须有v4包(android-support-v4.jar)。

2.9.2 其他注意事项

  • 推荐调用Register方法在MainActivity的onCreate中执行,防止其被多次调用。如果您在Application的派生类onCreate调用Register代码中需要注意防止多次初始化。
  • 原因:

    由于Application的实例是每个进程一个的,service和receiver各自工作在一个进程中,service为一个独立进程,receiver在UI进程。UI进程在应用到后台时很容易被清理,一旦接收到广播,如果UI进程已经被杀死,会导致进程重新被创建,Application的onCreate被调用。另外service在收到命令时如果其独立进程被杀死也会重新启动,也会触发Application的onCreate被调用。如果需要在Application的onCreate作初始化动作,可设置一个持久化标志来表示初始化动作是否被做过,或者还可以判断进程名字来区分是UI进程还是service独立进程做不同的初始化控制。