SDK集成
本节介绍如何将Android NPNS SDK开发包集成到移动应用MA中去。
在编写客户端应用代码之前,你需要做好以下准备:
- 获取MA开发所需的Application ID和Sender ID(从国信灵通官方获取)
- 获取相关的NPNS SDK开发包
- AS能向NPNS发出请求
集成NPNS SDK主要有以下几步:
- 验证SDK的完整性;
- 导入SDK至Eclipse工程;
- 配置AndroidManifest.xml;
- 参照API接口文档及Demo源码,实现应用BroadcastReceiver子类;
- 测试验证。
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

2.2 导入到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方式可以有两种:
- 在logcat中会打印出来;
- 在SD卡的NQ/NPNS/RegInfo/hesineRegInfo.txt会有regId的记录。
在查看SD卡的时候,不要用USB接口打开大容量存储的方式读取,而要用第三方工具如91助手或者从手机文件管理器中读取。
如能看到注册成功及RegID的记录,就说明SDK已经正常工作了。