SDK集成

本节介绍如何将Android NPNS SDK开发包集成到移动应用MA中去。

在编写客户端应用代码之前,你需要做好以下准备:

  • 获取MA开发所需的Application ID和Sender ID(从国信灵通官方获取)
  • 获取相关的NPNS SDK开发包
  • AS能向NPNS发出请求

集成NPNS SDK主要有以下几步:

  1. 验证SDK的完整性;
  2. 导入SDK至Eclipse工程;
  3. 配置AndroidManifest.xml;
  4. 参照API接口文档及Demo源码,实现应用BroadcastReceiver子类;
  5. 测试验证。

1. NPNS SDK开发包

解压之后应该包含以下文件,请确认文件是否包含完全。

  • SDK/AndroidManifest.xml: 应用的配置文件,需根据需要修改
  • SDK/libs/npns.jar:NPNS jar包
  • SDK/libs/armeabi/ libnpns.so:NPNS native库文件
  • demo:是一个完整的 Android 项目,它展示了Android NPNS SDK 的基本用法,可以用来做参考。

2. 导入NPNS SDK开发包到工程

下载Anroid NPNS SDK压缩包并解压至本地目录,复制libs到工程的根目录,该目录包含npns.jar和armeabi文件夹,armeabi文件夹中包含libnpns.so文件。如果工程存在该目录,则把libs里面的文件或者文件夹复制到libs目录中。

2.1 导入到Eclipse
导入到Eclipse

Eclipse

2.2 导入到Android Studio

导入Android Studio工程之后的结构如图:

Android Studio

3. 配置AndroidManifest.xml

根据压缩包里的AndroidManifest.xml, 你需要把以下的配置添加到自己的应用程序之中。

以下的配置除权限之外,其余都在application的节点之中。

3.1 添加权限

<!-- if you want to use NPNS SDK ,you should add follow permission -->
<!—下面两行的xxxx应该修改为你应用程序的包名-->
<permission android:name="xxxx.permission.MESSAGE" />
<uses-permission android:name="xxxx.permission.MESSAGE" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.DEVICE_POWER" />
<uses-permission android:name="android.permission.GET_TASKS" />
<uses-permission android:name="android.permission.READ_LOGS" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.WRITE_SETTINGS" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.INSTALL_PACKAGES" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.INTERNET" />

3.2 添加账号

<meta-data
android:name="NPNS_APP_ID"
 android:value="Your app ID" />
<meta-data
   android:name="NPNS_ACCOUNT_ID"
android:value="Your sender ID" />

其中的Your app ID 和 Your sender ID是你注册开发应用的时候获得的相关账号和信息,也就是上文中提到的Application ID和Sender ID,这部分详细内容请查看注册开发应用的相关介绍。

3.3 添加SDK的相关Services及组件

<!-- if you want to use NPNS SDK ,you should add follow content -->
<application
     android:name=".DemoApplication"
        >
<service android:name="com.nationsky.npns.Service" >
    <intent-filter>
          <action android:name="com.npns.android.intent.CHECK" />
          <action android:name="com.npns.android.intent.REGISTER" />
          <action android:name="com.npns.android.intent.UNREGISTER" />
          <action android:name="com.npns.android.intent.RECONNECT" />
     </intent-filter>
 </service>
 <receiver android:name="com.nationsky.npns.receiver.NpnsPackageReceiver" >
     <intent-filter>
           <action android:name="android.intent.action.PACKAGE_REMOVED" />
           <data android:scheme="package" />
      </intent-filter>
      <intent-filter>
           <action android:name="com.npns.android.intent.MASTERCHANGED" />
       </intent-filter>
 </receiver>
 <receiver android:name="com.nationsky.npns.receiver.NpnsAutoStartReceiver" >
       <intent-filter>
            <action android:name="android.intent.action.BOOT_COMPLETED" />
       </intent-filter>
 </receiver>
</application>

3.4 添加MA至BroadcastReceiver组件

NPNS通过发广播的方式向MA发送和推送消息。要获取NPNS发送的相关消息, MA需要注册相关的广播监听器。

一般来说,用户需要自定义一个用于接收NPNS消息的BroadcastReceiver类,其配置文件如下,其中xxxx为你自定义的类名,用户需要根据需要更改。

<receiver android:name=".xxxx
    <intent-filter>
         <action android:name="com.npns.android.intent.RECEIVE" />
     </intent-filter>
     <intent-filter>
          <action android:name="com.npns.android.intent.REGISTRATION" />
     </intent-filter>
     <intent-filter>
          <action android:name="com.npns.android.intent.UNREGISTER" />
     </intent-filter>
    <intent-filter>
          <action android:name="com.npns.android.intent.REGIDCHANGED" />
</intent-filter>
     <intent-filter>
          <action android:name="com.npns.android.intent.RECONNECT" />
</intent-filter>
</receiver>

4. API接口说明

在com.nationsky.npns的包中,SDK类对外提供如下接口:

接口函数 描述
public static void startService(Context context) 启动NPNS Services, 调用此接口启动NPNS。第一次运行时,需要调用该接口。
public static void onRegister(Context context) 注册NPNS接口,根据应用程序配置的appID和senderId向服务器注册该应用。每次app启动时,需要调用该接口。
public static void onUnregister(Context context) 注销NPNS服务接口。注销后,服务器不再给该应用推送消息。该接口用于停止指定app的NPNS服务。
public static void manuleRefresh(Context context) 手动更新,调用这个接口可以刷新连接,接收新消息。
public static void appReceiveOneMsg(Context context, String appId) 当应用收到NPNS推送的消息是,调用此接口,此接口会告知NPNS 应用已经收到了消息。

4.1 启动、注册、注销NPNS

在启动MA的Application的子类中可以调用如下代码就可以启动、注册NPNS。

在其他需要刷新,注销NPNS的地方可以调用相关的API函数。

下面是示例代码片段,详情可见Demo中的示例代码。需要留意的是,在AndroidManifest.xml要配置应用程序DemoApplication类。

public class DemoApplication extends Application {
    private static String TAG = "DemoApplication";
    public void onCreate(){
        super.onCreate();
        Log.i(TAG, "Enter application, and start to register to NPNS then check the version");
        SDK.startService(this);
        SDK.onRegister(this);
    }
}

 4.2 接收NPNS消息

在自定义的BroadcastReceiver子类中,接收消息的如下:

 public void onReceive(Context context, Intent intent) {
        String receiveAction = intent.getAction();
        if (receiveAction.equals(action_registration)) {
            //handleRegistration(context, intent);
        } else if (receiveAction.equals(action_unregister)) {
            //handleUnRegistration(context, intent);
        } else if(receiveAction.equals(action_regId_change)){
            //handleRegIdChange(context, intent);
        }else if (receiveAction.equals(action_receive)) {
              SDK.appReceiveOneMsg(context, "填写应用的 appId");
           // handleNewMessage(context, intent);
        } else if (receiveAction.equals(action_reconnect)) {
            //handleReconnect(context, intent);
        } else {
        }
    }

 4.3 NPNS广播的action、返回错误码及其信息提取

NPNS广播的Action定义如下:

说明 MA注册NPNS,返回时发送广播的action。MA在收到该广播后,应提取regID并立即上传至应用服务器。
获取数据

String regId = intent.getStringExtra(“registration_id”);

int errorCode = intent.getIntExtra(“code”, 0);

public static final String action_receive = “com.npns.android.intent.RECEIVE”;
说明 NPNS接收到消息,发送广播的action。
获取数据 String message = intent.getStringExtra(“message”);
public static final String action_unregister = “com.npns.android.intent.UNREGISTER”;
说明 MA注销NPNS,返回时发送广播的action。MA在收到注销返回广播后,应立即通知应用服务器删除已注销的regID。
获取数据 int errorCode = intent.getIntExtra(“code”, 0);
public static final String action_reconnect = “com.npns.android.intent.RECONNECT”;
说明 重新连接NPNS,返回时发送广播的action。MA在收到Reconnect返回广播后,应立即发起注册NPNS。
获取数据  public static final String action_registration = “com.npns.android.intent.REGISTRATION”;

返回错误码。需要特别留意,所有错误码均需要MA作相应的处理。

错误码 描述
0 操作成功,没有错误返回。
100/103 注册失败,请稍后再试。建议1分钟后重试,且重试间隔按指数增长:1/2/4/8…
101/104/105 服务不可用。请与国信灵通联系。
102 网络连接错误,请检查设备的网络连接。建议重试若干次,若仍失败,提示用户检查/恢复网络连接后再试。
151 表示注册提供的appId错误。一般在初次使用SDK时发生,请仔细核实,修正后重试。
152 表示注册提供的senderID错误。一般在初次使用SDK时发生,请仔细核实,修正后重试。

5.  测试SDK是否正常运行

检查配置:

  • 确认AndroidManifest.xml里的参数和必要的权限已正确添加。
  • 确认Application ID和Sender ID配置正确。
  • 确认在主的Activity中的对NPNS启动进行正确调用。
  • 确认你的测试设备能够连接网络。
  • 确认接收BroadcastReceiver已经实现。

测试NPNS SDK的Push Notification

  • 注册成功会在logCat中会有以下消息打印出来:Register nps successfully, regId: XXXXXXXXXXXXX

获取regId方式可以有两种:

  1. 在logcat中会打印出来;
  2. 在SD卡的NQ/NPNS/RegInfo/hesineRegInfo.txt会有regId的记录。

在查看SD卡的时候,不要用USB接口打开大容量存储的方式读取,而要用第三方工具如91助手或者从手机文件管理器中读取。

如能看到注册成功及RegID的记录,就说明SDK已经正常工作了。