Android SDK 进阶教程.docx

Android SDK 进阶教程.docx

《Android SDK 进阶教程.docx》由会员分享，可在线阅读，更多相关《Android SDK 进阶教程.docx（19页珍藏版）》请在冰豆网上搜索。

AndroidSDK进阶教程

AndroidSDK进阶教程

别名与标签使用教程

为什么需要别名与标签

推送消息时，要指定推送的对象：

全部，某一个人，或者某一群人。

全部很好办，针对某应用“群发”就好了。

Portal与API都支持向指定的appKey群发消息。

要指定向某一个特定的人，或者某一群特定的人，则相对复杂。

因为对于JPush来说，某一个人就是一个注册ID，这个注册ID与开发者App没有任何关系，或者说对开发者App是没有意义的。

如果要对开发者App有意义的某个特定的用户推送消息，则需要：

把JPush注册用户与开发者App用户绑定起来。

这个绑定有两个基本思路：

∙把绑定关系保存到JPush服务器端

∙把绑定关系保存到开发者应用服务器中

前者，就是这里要说到的：

别名与标签的功能。

这个机制简单易用，适用于大多数开发者。

后者，则是JPush提供的另外一套RegistrationID机制。

这套机制开发者需要有应用服务器来维护绑定关系，不适用于普通开发者。

AndroidSDKr1.6.0版本开始支持。

使用方式

别名与标签的机制，其工作方式是：

∙客户端开发者App调用setAliasAndTagsAPI来设置关系

∙JPushSDK把该关系设置保存到JPushServer上

∙在服务器端推送消息时，指定向之前设置过的别名或者标签推送

SDK支持的setAliasAndTags请参考相应的文档：

别名与标签API

使用过程中有几个点做特别说明：

∙App调用SDKsetAliasAndTagsAPI时，r1.5.0版本提供了Callback来返回设置状态。

如果返回6002（超时）则建议重试

o老版本没有提供Callback无设置状态返回，从而没有机制确定一定成功。

建议升级到新版本

∙Portal上推送或者API调用向别名或者标签推送时，可能会报错：

不存在推送目标用户。

该报错表明，JPushServer上还没有针对你所推送的别名或者标签的用户绑定关系，所以没有推送目标。

这时请开发者检查确认，开发者App是否正确地调用了setAliasAndTagsAPI，以及调用时是否网络不好，JPushSDK暂时未能保存成功。

使用别名

用于给某特定用户推送消息。

别名，可以近似地被认为，是用户帐号里的昵称。

比如账号昵称（臧廷杰，系统里就制定为zangtingjie）

使用标签

用于给某一群人推送消息。

标签类似于博客里为文章打上tag，即为某资源分类。

动态标签

JPush提供的设置标签的API是在客户端的。

开发者如何做到在自己的服务器端动态去设置分组呢？

比如一个企业OA系统，经常需要去变更部门人员分组。

以下是大概的思路：

∙设计一种自定义消息格式（业务协议），App解析后可以调用JPushSDKsetAliasAndTagsAPI来重新设置标签（分组）

o例：

{"action":

"resetTags","newTags":

["dep_level_1":

"A公司","dep_level_2":

"技术部","dep_level_3":

"Android开发组","address":

"深圳","lang":

"zh"]}

∙要动态设置分组时，推送这条自定义消息给指定的用户

o使用别名的机制，推送到指定的用户。

∙客户端App调用JPushSDKAPI来设置新的标签

别名与标签设置异常处理

由于网络连接不稳定的原因，有一定的概率JPushSDK设置别名与标签会失败。

App开发者合理地处理设置失败，则偶尔失败对应用的正常使用JPush影响是有限的。

以下以AndroidSDK作为示例。

基本思路：

∙设置成功时，往SharePreference里写状态，以后不必再设置

∙遇到6002超时，则稍延迟重试。

∙//这是来自JPushExample的设置别名的Activity里的代码。

一般App的设置的调用入口，在任何方便的地方调用都可以。

∙privatevoidsetAlias（）{

∙    EditTextaliasEdit=（EditText）findViewById（R.id.et_alias）;

∙    Stringalias=aliasEdit.getText（）.toString（）.trim（）;

∙    if（TextUtils.isEmpty（alias））{

∙        Toast.makeText（PushSetActivity.this,R.string.error_alias_empty,Toast.LENGTH_SHORT）.show（）;

∙        return;

∙    }

∙    if（!

ExampleUtil.isValidTagAndAlias（alias））{

∙        Toast.makeText（PushSetActivity.this,R.string.error_tag_gs_empty,Toast.LENGTH_SHORT）.show（）;

∙        return;

∙    }

∙

∙    //调用Handler来异步设置别名

∙    mHandler.sendMessage（mHandler.obtainMessage（MSG_SET_ALIAS,alias））;

∙}

∙

∙privatefinalTagAliasCallbackmAliasCallback=newTagAliasCallback（）{

∙    @Override

∙    publicvoidgotResult（intcode,Stringalias,Settags）{

∙        Stringlogs;

∙        switch（code）{

∙        case0:

∙            logs="Settagandaliassuccess";

∙            Log.i（TAG,logs）;

∙            //建议这里往SharePreference里写一个成功设置的状态。

成功设置一次后，以后不必再次设置了。

∙            break;

∙        case6002:

∙            logs="Failedtosetaliasandtagsduetotimeout.Tryagainafter60s.";

∙            Log.i（TAG,logs）;

∙            //延迟60秒来调用Handler设置别名

∙            mHandler.sendMessageDelayed（mHandler.obtainMessage（MSG_SET_ALIAS,alias）,1000*60）;

∙            break;

∙        default:

∙            logs="FailedwitherrorCode="+code;

∙            Log.e（TAG,logs）;

∙        }

∙        ExampleUtil.showToast（logs,getApplicationContext（））;

∙    }

∙};

∙privatestaticfinalintMSG_SET_ALIAS=1001;

∙privatefinalHandlermHandler=newHandler（）{

∙@Override

∙    publicvoidhandleMessage（android.os.Messagemsg）{

∙        super.handleMessage（msg）;

∙        switch（msg.what）{

∙        caseMSG_SET_ALIAS:

∙        Log.d（TAG,"Setaliasinhandler."）;

∙            //调用JPush接口来设置别名。

∙            JPushInterface.setAliasAndTags（getApplicationContext（）,

∙            （String）msg.obj,

∙            null,

∙            mAliasCallback）;

∙            break;

∙        default:

∙            Log.i（TAG,"Unhandledmsg-"+msg.what）;

∙        }

∙    }                

∙};

自定义通知栏样式教程

关于自定义通知栏样式

JPush通知推送到客户端时，默认使用手机的默认设置来显示通知栏，包括铃声、震动等效果。

如果开发者想要达到如下的效果，则需要使用“自定义通知栏样式”功能：

∙通知栏样式使用与默认不一样的设置，比如想要控制：

o铃声、震动

o显示图标

o替换默认的通知栏样式。

推送消息指定通知栏样式编号

通知栏样式在服务器端向下推送时，只体现为一个编号（数字）。

推送通知的样式编号，应该是在客户端做了自定义通知栏样式设置的。

如果通知上的样式编号，在客户端检查不存在，则使用默认的通知栏样式。

不使用自定义通知栏样式时，此编号默认为0。

如需使用自定义的通知栏样式，编号应大于0，小于1000。

在Portal上发送通知时，最下边的“可选”部分展开，开发者可指定当前要推送的通知的样式编号。

如下图所示：

客户端设置通知栏样式

自定义的通知栏样式，是在客户端进行设置的。

请参考 通知栏样式定制API 来看所支持的功能。

自定义通知栏样式设计

∙有个PushNotificationBuilder概念，开发者使用setPushNotificationBuilder方法为某种类型的PushNotificationBuilder指定编号。

∙setPushNotificationBuilder可以在JPushInterface.init（）之后任何地方调用，可以是开发者应用的逻辑来触发调用，或者初始化时调用。

∙只需要设置一次，JPushSDK会记住这个设置。

在下次收到推送通知时，就根据通知里指定的编号来找到PushNotificationBuilder来展现、执行。

API-setDefaultPushNotificationBuilder设置默认

此API改变默认的编号为0的通知栏样式。

API-setPushNotificationBuilder指定编号

此API为开发者指定的编号，设置一个自定义的PushNotificationBuilder（通知样式构建器）。

Example-基础的PushNotificationBuilder

定制声音、震动、闪灯等Notification样式。

BasicPushNotificationBuilderbuilder=newBasicPushNotificationBuilder（MainActivity.this）;

builder.statusBarDrawable=R.drawable.jpush_notification_icon;

builder.notificationFlags=Notification.FLAG_AUTO_CANCEL

|Notification.FLAG_SHOW_LIGHTS; //设置为自动消失和呼吸灯闪烁

builder.notificationDefaults=Notification.DEFAULT_SOUND

|Notification.DEFAULT_VIBRATE

|Notification.DEFAULT_LIGHTS; //设置为铃声、震动、呼吸灯闪烁都要

JPushInterface.setPushNotificationBuilder（1,builder）;

定制带按钮的Notification样式（3.0.0及以上版本sdk才支持该样式，且该样式在某些与Android原生系统有差异的机型上无法正常显示）。

MultiActionsNotificationBuilderbuilder=newMultiActionsNotificationBuilder（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（2,builder）;

Example-高级自定义的PushNotificationBuilder

基于基础的PushNotificationBuilder，可进一步地定制Notification的Layout。

这里作为example的customer_notitfication_layout在我们的example项目的/res/layout/下可以找到。

你完全可以用自己的layout。

CustomPushNotificationBuilderbuilder=new

CustomPushNotificationBuilder（MainActivity.this,

    R.layout.customer_notitfication_layout,

    R.id.icon,

    R.id.title,

    R.id.text）; 

   //指定定制的NotificationLayout

builder.statusBarDrawable=R.drawable.your_notification_icon;     

//指定最顶层状态栏小图标

builder.layoutIconDrawable=R.drawable.your_2_notification_icon;  

//指定下拉状态栏时显示的通知图标

JPushInterface.setPushNotificationBuilder（2,builder）;

通知栏样式定义不符合要求？

以上提供的自定义通知栏样式的功能是有限的。

比如：

AndroidSDK4.0以后的 Notification 支持指定Style，而这种复杂的通知样式定义JPushSDK还未有支持。

或者你想要自定义的复杂的通知样式，但不愿意使用上述高级的自定义通知栏定制功能。

建议不要使用JPush提供的通知功能，而使用自定义消息功能。

即：

推送自定义消息到客户端后，App取到自定义消息全部内容，然后App自己来写代码做通知的展示。

请参考文档：

通知vs.自定义消息。

通知vs自定义消息

极光推送包含有通知与自定义消息两种类型的推送。

本文描述他们的区别，以及建议的应用场景。

两者的区别-功能角度

通知

通知（Notification），指在手机的通知栏（状态栏）上会显示的一条通知信息。

这是Android/iOS的基本功能。

通知主要用于提示用户。

一条通知，简单的填写纯文本的通知内容即可。

应用加上通知功能，有利于提高应用的活跃度。

自定义消息

自定义消息不是通知，默认不会被SDK展示到通知栏上，极光推送仅负责透传给SDK。

其内容和展示形式完全由开发者自己定义。

自定义消息主要用于应用的内部业务逻辑和特殊展示需求。

两者的区别-开发者使用角度

通知

简单场景下的通知，用户可以不写一行代码，而完全由SDK来负责默认的效果展示，以及默认用户点击时打开应用的主界面。

JPushAndroidSDK提供了API让开发者来定制通知栏的效果，请参考：

自定义通知栏样式教程；也提供了接收推送消息Receiver让你来定制在收到通知时与用户点击通知时的不同行为。

自定义消息

SDK不会把自定义消息展示到通知栏。

所以调试时，需要到日志里才可以看到服务器端推送的自定义消息。

自定义消息一定要由开发者写 接收推送消息Receiver 来处理收到的消息。

注意：

当自定义消息内容msg_content为空时，SDK不会对消息进行广播，使得app无法接收到推送的消息，因此建议在使用自定义消息推送时添加内容。

使用通知

请参考以下示例代码。

publicclassMyReceiverextendsBroadcastReceiver{

    privatestaticfinalStringTAG="MyReceiver";

    privateNotificationManagernm;

    @Override

    publicvoidonReceive（Contextcontext,Intentintent）{

        if（null==nm）{

            nm=（NotificationManager）context.getSystemService（Context.NOTIFICATION_SERVICE）;

        }

        Bundlebundle=intent.getExtras（）;

        Logger.d（TAG,"onReceive-"+intent.getAction（）+",extras:

"+AndroidUtil.printBundle（bundle））;

        if（JPushInterface.ACTION_REGISTRATION_ID.equals（intent.getAction（）））{

            Logger.d（TAG,"JPush用户注册成功"）;

        }elseif（JPushInterface.ACTION_MESSAGE_RECEIVED.equals（intent.getAction（）））{

            Logger.d（TAG,"接受到推送下来的自定义消息"）;

        }elseif（JPushInterface.ACTION_NOTIFICATION_RECEIVED.equals（intent.getAction（）））{

            Logger.d（TAG,"接受到推送下来的通知"）;

            receivingNotification（context,bundle）;

        }elseif（JPushInterface.ACTION_NOTIFICATION_OPENED.equals（intent.getAction（）））{

            Logger.d（TAG,"用户点击打开了通知"）;

           openNotification（context,bundle）;

        }else{

            Logger.d（TAG,"Unhandledintent-"+intent.getAction（））;

        }

    }

   privatevoidreceivingNotification（Contextcontext,Bundlebundle）{

        Stringtitle=bundle.getString（JPushInterface.EXTRA_NOTIFICATION_TITLE）;

        Logger.d（TAG,"title:

"+title）;

        Stringmessage=bundle.getString（JPushInterface.EXTRA_ALERT）;

        Logger.d（TAG,"message:

"+message）;

        Stringextras=bundle.getString（JPushInterface.EXTRA_EXTRA）;

        Logger.d（TAG,"extras:

"+extras）;

    }

   privatevoidopenNotification（Contextcontext,Bundlebundle）{

        Stringextras=bundle.getString（JPushInterface.EXTRA_EXTRA）;

        StringmyValue="";

        try{

            JSONObjectextrasJson=newJSONObject（extras）;

            myValue=extrasJson.optString（"myKey"）;

        }catch（Exceptione）{

            Logger.w（TAG,"Unexpected:

extrasisnotavalidjson",e）;

            return;

        }

        if（TYPE_THIS.equals（myValue））{

            IntentmIntent=newIntent（context,ThisActivity.class）;

            mIntent.putExtras（bundle）;