diff --git a/README.md b/README.md index 0d6c9b0..49ee46c 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,13 @@ 2. 添加平台 - cd Myproj :不进入项目会出现[RangeError:Maximum call stack size exceeded] + cd Myproj cordova platform add android cordova platform add ios + ps:这里请注意iOS平台，必须先执行 `cordova platform add ios`, + 然后再执行`cordova plugin add xxxxx`命令，不然有一些必须要的链接库需要手动添加 + ### Android使用PhoneGap/Cordova CLI自动安装 1. 使用git命令将jpush phonegap插件下载的本地,将这个目录标记为`$JPUSH_PLUGIN_DIR` @@ -37,251 +40,50 @@ ###IOS使用PhoneGap/Cordova CLI自动安装 -1. 使用PhoneGap/Cordova CLI命令安装 +1. 使用PhoneGap/Cordova CLI添加jpush phonegap插件和依赖的device插件 cordova plugin add https://github.com/jpush/jpush-phonegap-plugin.git - cordova build ios + cordova plugin add org.apache.cordova.device -2. 修改Resources/PushConfig.plist文件 +3. 修改Resources/PushConfig.plist文件 -在APP_KEY和CHANNLE字段 分别添加您的appkey和channle + + 在APP_KEY和CHANNLE字段 分别添加您的appkey和channle -3. 在AppDelegate.m中包含头文件 +4. 在AppDelegate.m中包含头文件 #import "APService.h" #import "JPushPlugin.h" - -4. 在AppDelegate.m文件中，调用 JPush SDK 提供的 API 来实现功能 - +5. 在AppDelegate.m文件中，添加JPush SDK 提供的 API 来实现功能 - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions{ - #if __has_feature(objc_arc) - self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]]; - #else - self.window = [[[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]] autorelease]; - #endif - self.window.backgroundColor = [UIColor whiteColor]; - [self.window makeKeyAndVisible]; - // Required - #if __IPHONE_OS_VERSION_MAX_ALLOWED > __IPHONE_7_1 -    if ([[UIDevice currentDevice].systemVersion floatValue] >= 8.0) { -     //可以添加自定义categories -     [APService registerForRemoteNotificationTypes:(UIUserNotificationTypeBadge | -                                                    UIUserNotificationTypeSound | -                                                    UIUserNotificationTypeAlert) -                                        categories:nil]; -   } else { -     //categories 必须为nil -     [APService registerForRemoteNotificationTypes:(UIRemoteNotificationTypeBadge | -                                                    UIRemoteNotificationTypeSound | -                                                    UIRemoteNotificationTypeAlert) -                                        categories:nil]; -   } - #else -     //categories 必须为nil -   [APService registerForRemoteNotificationTypes:(UIRemoteNotificationTypeBadge | -                                                  UIRemoteNotificationTypeSound | -                                                  UIRemoteNotificationTypeAlert) -                                      categories:nil]; - #endif -     // Required -     [APService setupWithOption:launchOptions]; -     [JPushPlugin setLaunchOptions:launchOptions]; - + //原内容保持不变 + //Required add + [JPushPlugin setLaunchOptions:launchOptions]; return YES; } - - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken { - // Required + - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken { + //原内容保持不变 + // Required add [APService registerDeviceToken:deviceToken]; } - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo { + //原内容保持不变 // Required [APService handleRemoteNotification:userInfo]; [[NSNotificationCenter defaultCenter] postNotificationName:kJPushPluginReceiveNotification - object:userInfo]; - + object:userInfo]; } -###Android 手工安装### -1. 复制src/android/*.java 到cn/jpush/phonega/目录下(即：cn.jpush.phonegap的包下) -2. 复制src/android/armeabi/libjpush.so 到lib/armeabi/ -3. 复制src/android/jpush-sdk-release1.5.0.jar 到lib/ -4. 复制src/android/test_notification_layout.xml到res/layout/ -5. 复制src/android/jpush_notification_icon.png 到res/drawable/ -6. 修改 AndroidManifest.xml 在 manifest 节点下添加以下权限 - - - - - - - - - - - - - - - -7. 修改AndroidManifest.xml 在 manifest/application 节点下添加SDK相关组件声明 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +### Android 手工安装 +[Android 手工安装文档地址](document/Android_handle_install.md) + ### IOS手工安装 -1. 添加src/ios/Plugins/到project中 -2. 添加src/ios/lib/到project中 -3. 设置 Search Paths 下的 User Header Search Paths 和 Library Search Paths +[IOS手工安装文档地址](document/iOS_handle_install.md) -比如SDK文件夹（默认为lib）与工程文件在同一级目录下，则都设置为"$(SRCROOT)/[文件夹名称]"即可。 - -4. 确认一下的框架是存在的(Target -> Build Phases -> Link Binary With Libraries) - - CFNetwork.framework - CoreFoundation.framework - CoreTelephony.framework - SystemConfiguration.framework - CoreGraphics.framework - Foundation.framework - UIKit.framework - - -5. 在你的工程中创建一个新的Property List文件 - - 并将其命名为PushConfig.plist，填入Portal为你的应用提供的APP_KEY等参数 - - -6. 调用代码,监听系统事件，相应地调用 JPush SDK 提供的 API 来实现功能 - - - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions - { - #if __has_feature(objc_arc) - self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]]; - #else - self.window = [[[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]] autorelease]; - #endif - self.window.backgroundColor = [UIColor whiteColor]; - [self.window makeKeyAndVisible]; - - // Required - [APService registerForRemoteNotificationTypes:(UIRemoteNotificationTypeBadge | - UIRemoteNotificationTypeSound | - UIRemoteNotificationTypeAlert)]; - // Required - [APService setupWithOption:launchOptions]; - - return YES; - } - - - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken { - - // Required - [APService registerDeviceToken:deviceToken]; - } - - - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo { - - // Required - [APService handleRemoteNotification:userInfo]; - } - - -7. 修改phonegap config.xml文件用来包含Plugin/内的插件 - - - - - - - - -8. 复制www/PushNotification.js到工程的www目录下面 -9. 在需要使用插件处加入 - - ###示例 @@ -293,6 +95,7 @@ ###关于'phonegap build'云服务 该项目基于cordova实现，目前无法使用'phonegap build'云服务进行打包，建议使用本地环境进行打包 + ###常见错误 1. androd @@ -306,621 +109,98 @@ * android:[YOUR__ANDROID_PROJECT]/assets/www/plugins/cn.jpush.phonegap.JPushPlugin/www * iOS:[YOUR_iOS_PROJEcT]/www/plugins/cn.jpush.phonegap.JPushPlugin/www -这里只说明public的函数 +具体的API请参考这里 +#### iOS和adnroid通用API简介 ++ 获取 RegistrationID API -#### API - getRegistrationID - -RegistrationID 定义 - -集成了 JPush SDK 的应用程序在第一次成功注册到 JPush 服务器时，JPush 服务器会给客户端返回一个唯一的该设备的标识 - RegistrationID。JPush SDK 会以广播的形式发送 RegistrationID 到应用程序。 - -应用程序可以把此 RegistrationID 保存以自己的应用服务器上，然后就可以根据 RegistrationID 来向设备推送消息或者通知。 - - - -##### 接口定义 - - JPushPlugin.prototype.getRegistrationID = function(callback) - -##### 参数说明 -无 -##### 返回值 - -调用此 API 来取得应用程序对应的 RegistrationID。 只有当应用程序成功注册到 JPush 的服务器时才返回对应的值，否则返回空字符串。 - -##### 调用示例 - - window.plugins.jPushPlugin.getRegistrationID(onGetRegistradionID); - var onGetRegistradionID = function(data) { - try{ - console.log("JPushPlugin:registrationID is "+data) } - catch(exception){ - console.log(exception); - } - } - - -#### API - setTagsWithAlias,setTags,setAlias - -提供几个相关 API 用来设置别名（alias）与标签（tags）。 - -这几个 API 可以在 App 里任何地方调用。 - -别名 alias - -为安装了应用程序的用户，取个别名来标识。以后给该用户 Push 消息时，就可以用此别名来指定。 - -每个用户只能指定一个别名。 - -同一个应用程序内，对不同的用户，建议取不同的别名。这样，尽可能根据别名来唯一确定用户。 - -系统不限定一个别名只能指定一个用户。如果一个别名被指定到了多个用户，当给指定这个别名发消息时，服务器端API会同时给这多个用户发送消息。 - -举例：在一个用户要登录的游戏中，可能设置别名为 userid。游戏运营时，发现该用户 3 天没有玩游戏了，则根据 userid 调用服务器端API发通知到客户端提醒用户。 - -标签 tag - -为安装了应用程序的用户，打上标签。其目的主要是方便开发者根据标签，来批量下发 Push 消息。 - -可为每个用户打多个标签。 - -不同应用程序、不同的用户，可以打同样的标签。 - -举例： game, old_page, women - -##### 接口定义 - - JPushPlugin.prototype.setTagsWithAlias = function(tags,alias) - JPushPlugin.prototype.setTags = function(tags) - JPushPlugin.prototype.setAlias = function(alias) - -#####使用平台 -android iOS - - -##### 参数说明 -* tags - * 参数类型为数组 - * nil 此次调用不设置此值 - * 空集合表示取消之前的设置 - * 每次调用至少设置一个 tag，覆盖之前的设置，不是新增 - * 有效的标签组成：字母（区分大小写）、数字、下划线、汉字 - * 限制：每个 tag 命名长度限制为 40 字节，最多支持设置 100 个 tag，但总长度不得超过1K字节。（判断长度需采用UTF-8编码） - * 单个设备最多支持设置 100 个 tag。App 全局 tag 数量无限制。 -* alias - * 参数类型为字符串 - * nil 此次调用不设置此值 - * 空字符串 （""）表示取消之前的设置 - * 有效的别名组成：字母（区分大小写）、数字、下划线、汉字。 - * 限制：alias 命名长度限制为 40 字节。（判断长度需采用UTF-8编码） - -##### 返回值说明 - -函数本身无返回值，但需要注册`jpush.setTagsWithAlias `事件来监听设置结果 - - document.addEventListener("jpush.setTagsWithAlias", onTagsWithAlias, false); - var onTagsWithAlias = function(event){ - try{ - console.log("onTagsWithAlias"); - var result="result code:"+event.resultCode+" "; - result+="tags:"+event.tags+" "; - result+="alias:"+event.alias+" "; - $("#tagAliasResult").html(result); - } - catch(exception){ - console.log(exception) - } - } - - -#####错误码定义 - - -|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 字节| -|6011| 10s内设置tag或alias大于3次| 短时间内操作过于频繁| - - -#### API - startLogPageView,stopLogPageView,beginLogPageView - -本 API 用于“用户指定页面使用时长”的统计，并上报到服务器，在 Portal 上展示给开发者。页面统计集成正确，才能够获取正确的页面访问路径、访问深度（PV）的数据。 - -##### 接口定义 - JPushPlugin.prototype.startLogPageView = function(pageName) - JPushPlugin.prototype.stopLogPageView = function(pageName) - JPushPlugin.prototype.beginLogPageView = function(pageName,duration) - -#####平台 -iOS - -#####参数说明 -pageName 需要统计页面自定义名称 -duration 自定义的页面时间 - -#####调用说明 -应在所有的需要统计得页面得 viewWillAppear 和 viewWillDisappear 加入 startLogPageView 和 stopLogPageView 来统计当前页面的停留时间。 - - 或者直接使用 beginLogPageView 来自定义加入页面和时间信息。 - - -#####返回值说明 -无 - -#####代码示例 - - if(window.plugins.jPushPlugin.isPlatformIOS()){ - window.plugins.jPushPlugin.beginLogPageView("newPage",5); - window.plugins.jPushPlugin.startLogPageView("onePage"); - window.plugins.jPushPlugin.stopLogPageView("onePage"); - } - - - -#### API - setBadge,resetBadge - -badge是iOS用来标记应用程序状态的一个数字，出现在程序图标右上角。 JPush封装badge功能，允许应用上传badge值至JPush服务器，由JPush后台帮助管理每个用户所对应的推送badge值，简化了设置推送badge的操作。 - -实际应用中，开发者可以直接对badge值做增减操作，无需自己维护用户与badge值之间的对应关系。 - -##### 接口定义 - - JPushPlugin.prototype.setBadge = function(value) - JPushPlugin.prototype.resetBadge = function() - -`resetBadge相当于setBadge(0)` - -##### 平台 -iOS - -##### 参数说明 - -value 取值范围：[0,99999] - -##### 返回值 - -无，控制台会有log打印设置结果 - - -#####代码示例 - - if(window.plugins.jPushPlugin.isPlatformIOS()){ - window.plugins.jPushPlugin.setBadge(5); - window.plugins.jPushPlugin.reSetBadge(); - } -#### API - setDebugModeFromIos - -API 用于开启Debug模式，显示更多的日志信息 - -建议调试时开启这个选项，不调试的时候注释这句代码，这个函数setLogOFF是相反的一对 - -##### 接口定义 - - JPushPlugin.prototype.setDebugModeFromIos = function() - -##### 平台 -iOS - -#####代码示例 - - if(window.plugins.jPushPlugin.isPlatformIOS()){ - window.plugins.jPushPlugin.setDebugModeFromIos(); - } - -#### API - setLogOFF - -API用来关闭日志信息（除了必要的错误信息） - -不需要任何调试信息的时候，调用此API （发布时建议调用此API，用来屏蔽日志信息，节省性能消耗) - -##### 平台 -iOS - -##### 接口定义 - - JPushPlugin.prototype.setLogOFF = function() - -#####代码示例 - - if(window.plugins.jPushPlugin.isPlatformIOS()){ - window.plugins.jPushPlugin.setLogOFF(); - } - -#### API - receiveMessageIniOSCallback - -用于iOS收到应用内消息的回调函数(请注意和通知的区别)，该函数不需要主动调用 - -##### 接口定义 - - JPushPlugin.prototype.receiveMessageIniOSCallback = function(data) - - -#####平台 -iOS - -#####参数说明 - -- data 是一个js字符串使用如下代码解析，js具体key根据应用内消息来确定 - - var bToObj = JSON.parse(data); + window.plugins.jPushPlugin.getRegistrationID(callback) -#####返回值 -无 ++ 别名与标签 API + + window.plugins.jPushPlugin.setTagsWithAlias(tags,alias) + window.plugins.jPushPlugin.setTags(tags) + window.plugins.jPushPlugin.setAlias(alias) -#### event - jpush.receiveNotification -当iOS收到的通知时会触发这个事件 +[通用API详细说明](document/Common_detail_api.md) -##### 事件定义 +#### iOS API简介 ++ 获取 APNs（通知） 推送内容 - cordova.fireDocumentEvent('jpush.receiveNotification',json) + event - jpush.receiveNotification + event - jpush.openNotification -#####平台 -iOS ++ 获取自定义消息推送内容 -#####使用说明 + window.plugins.jPushPlugin.receiveMessageIniOSCallback(data) ++ 页面的统计 + + window.plugins.jPushPlugin.startLogPageView (pageName) + window.plugins.jPushPlugin.stopLogPageView (pageName) + window.plugins.jPushPlugin.beginLogPageView (pageName,duration) ++ 设置Badge -- 在你需要接收通知的的js文件中加入: - - document.addEventListener("jpush.receiveNotification", onReceiveNotification, false); - -- onOpenNotification需要这样写： + window.plugins.jPushPlugin.setBadge(value) + window.plugins.jPushPlugin.resetBadge() + window.plugins.jPushPlugin.setApplicationIconBadgeNumber(badge) ++ 本地通知 + 后续版本加入 - var onReceiveNotification = function(event){ - try{ - var alert = event.aps.alert; - console.log("JPushPlugin:onReceiveNotification key aps.alert:"+alert); - } - catch(exeption){ - console.log(exception) - } - } - ++ 日志等级设置 + window.plugins.jPushPlugin.setDebugModeFromIos () + window.plugins.jPushPlugin.setLogOFF() -#####返回值 -无 +[iOS API详细说明](document/iOS_detail_api.md) -#### event - jpush.openNotification - -当iOS收到的通知时会触发这个事件 - -##### 事件定义 - - cordova.fireDocumentEvent('jpush.openNotification',json) - -#####平台 -iOS - -#####使用说明 - -- 在你需要接收通知的的js文件中加入: - - document.addEventListener("jpush.openNotification", onOpenNotification, false); - -- onOpenNotification需要这样写： +#### adnroid API简介 ++ 停止与恢复推送服务 API - var onOpenNotification = function(event){ - try{ - - var alert = event.aps.alert; - console.log("JPushPlugin:onPpenNotification key aps.alert:"+alert); - } - catch(exception){ - console.log("JPushPlugin:onPpenNotification"+exception); - } - } - - -#### API - setApplicationIconBadgeNumber - -设置iOS的角标，当设置badge＝0时为清除角标 - - -##### 接口定义 - - JPushPlugin.prototype.setApplicationIconBadgeNumber = function(badge) + window.plugins.jPushPlugin.init() + window.plugins.jPushPlugin.stopPush() + window.plugins.jPushPlugin.resumePush() + window.plugins.jPushPlugin.isPushStopped(callback) + ++ 获取集成日志 -#####平台 -iOS - -##### 参数说明 -- data js字符串 - -##### 返回值 -无 - - - - -#### API - init - -调用此API,用来 -JPush SDK 提供的推送服务是默认开启的。 - - -##### 接口定义 - - JPushPlugin.prototype.init = function() - -##### 参数说明 -无 -##### 返回值 -无 - - -#### API - setDebugMode - -用于开启调试模式，可以查看集成JPush过程中的log，如果集成失败，可方便定位问题所在 - -##### 接口定义 - - JPushPlugin.prototype.setDebugMode = function(mode) - -##### 参数说明 - -- num 保存的条数 - -##### 返回值 -无 - - - -#### API - stopPush - - -开发者App可以通过调用停止推送服务API来停止极光推送服务。当又需要使用极光推送服务时，则必须要调用恢复推送服务 API。 - -在android平台 -调用了本 API 后，JPush 推送服务完全被停止。具体表现为： - -－ JPush Service 不在后台运行 -－ 收不到推送消息 -－ 不能通过 JPushInterface.init 恢复，需要调用resumePush恢复 -－ 极光推送所有的其他 API 调用都无效 - -在iOS推荐调用这个API，因为这个API只是让你的DeviceToken失效，在设置－通知 中您的应用程序没有任何变化 - -##### 接口定义 - - JPushPlugin.prototype.stopPush = function() - -#####平台 -android，iOS - - -##### 参数说明 -无 -##### 返回值 -无 - -#### API - resumePush - -恢复推送服务。 -调用了此 API 后，在android平台上极光推送完全恢复正常工作，在iOS平台上重新去APNS注册 - -#####平台 -android iOS - -##### 接口定义 - - JPushPlugin.prototype.resumePush = function() - - -##### 参数说明 -无 -##### 返回值 -无 - -#### API - isPushStopped - -在android 用来检查 Push Service 是否已经被停止 -在iOS 平台检查推送服务是否注册 - -##### 接口定义 - - JPushPlugin.prototype.isPushStopped = function(callback) - - -#####平台 -android iOS - -##### 参数说明 - -+ callback 回调函数，用来通知JPush的推送服务是否开启 - - var onCallback = function(data) { - if(data>0){ - //开启 - }else{ - //关闭 - } - } - -##### 返回值 -无 - - - -#### API - setBasicPushNotificationBuilder,setCustomPushNotificationBuilder - -当用户需要定制默认的通知栏样式时，则可调用此方法。 -极光 Push SDK 提供了 2 个用于定制通知栏样式的构建类： - -- setBasicPushNotificationBuilder - - Basic 用于定制 Android Notification 里的 defaults / flags / icon 等基础样式（行为） -- setCustomPushNotificationBuilder - - 继承 Basic 进一步让开发者定制 Notification Layout - -如果不调用此方法定制，则极光Push SDK 默认的通知栏样式是：Android标准的通知栏提示。 - -#####平台 -android - -##### 接口定义 - - JPushPlugin.prototype.setBasicPushNotificationBuilder = function() - JPushPlugin.prototype.setCustomPushNotificationBuilder = function() - -#### 参数说明 - -无 - -##### 返回值 - -无 - -#### API - clearAllNotification - -推送通知到客户端时，由 JPush SDK 展现通知到通知栏上。 - -此 API 提供清除通知的功能，包括：清除所有 JPush 展现的通知（不包括非 JPush SDK 展现的） - - -##### 接口定义 - - JPushPlugin.prototype.clearAllNotification = function() - -#####平台 -android - -##### 参数说明 -无 -##### 返回值 -无 - -#### API - setLatestNotificationNum - -通过极光推送，推送了很多通知到客户端时，如果用户不去处理，就会有很多保留在那里。 - -新版本 SDK (v1.3.0) 增加此功能，限制保留的通知条数。默认为保留最近 5 条通知。 - -开发者可通过调用此 API 来定义为不同的数量。 - - - -##### 接口定义 - - JPushPlugin.prototype.setLatestNotificationNum = function(num) - - -#####平台 -android - -##### 参数说明 - -- num 保存的条数 - -##### 返回值 -无 - - -#### API - addLocalNotification,removeLocalNotification,clearLocalNotifications - - -本地通知API不依赖于网络，无网条件下依旧可以触发 - -本地通知与网络推送的通知是相互独立的，不受保留最近通知条数上限的限制 - -本地通知的定时时间是自发送时算起的，不受中间关机等操作的影响 - - -三个接口的功能分别为：添加一个本地通知，删除一个本地通知，删除所有的本地通知 - -#####接口定义 - - JPushPlugin.prototype.addLocalNotification = function(builderId, - content, - title, - notificaitonID, - broadcastTime, - extras) - JPushPlugin.prototype.removeLocalNotification = function(notificationID) - JPushPlugin.prototype.clearLocalNotifications = function() - -#####平台 -android - -##### 参数说明 - -- builderId 设置本地通知样式 -- content 设置本地通知的content -- title 设置本地通知的title -- notificaitonID 设置本地通知的ID -- broadcastTime 设置本地通知触发时间，为距离当前时间的数值，单位是毫秒 -- extras 设置额外的数据信息extras为json字符串 - -##### 返回值说明 - -无 - - -#### API - receiveMessageInAndroidCallback - -用于android收到应用内消息的回调函数(请注意和通知的区别)，该函数不需要主动调用 - -##### 接口定义 - - JPushPlugin.prototype.receiveMessageInAndroidCallback = function(data) - -#####平台 -android - -##### 参数说明 -- data 接收到的js字符串，包含的key:value请进入该函数体查看 - -##### 返回值 -无 - - -#### API - reportNotificationOpened - -用于上报用户的通知栏被打开，或者用于上报用户自定义消息被展示等客户端需要统计的事件。 - - -##### 接口定义 - - JPushPlugin.prototype.reportNotificationOpened = function(msgID) - -#####平台 -android - -##### 参数说明 -- 无 - -##### 返回值 -无 - -#### API - openNotificationInAndroidCallback - -当点击android手机的通知栏进入应用程序时,会调用这个函数，这个函数不需要主动调用，是作为回调函数来用的 - - -##### 接口定义 - - JPushPlugin.prototype.openNotificationInAndroidCallback = function(data) - -#####平台 -android - -##### 参数说明 -- data js字符串 - -##### 返回值 -无 - - - - - + window.plugins.jPushPlugin.setDebugMode(mode) + ++ 接收推送消息Receiver + + window.plugins.jPushPlugin.receiveMessageInAndroidCallback(data) + window.plugins.jPushPlugin.openNotificationInAndroidCallback(data) + ++ 统计分析 API + + onResume / onPause(java api) + + ++ 清除通知 API + + window.plugins.jPushPlugin.clearAllNotification() + ++ 通知栏样式定制 API + + window.plugins.jPushPlugin.setBasicPushNotificationBuilder = function() + window.plugins.jPushPlugin.setCustomPushNotificationBuilder = function() + ++ 设置保留最近通知条数 API + + window.plugins.jPushPlugin.setLatestNotificationNum(num) + ++ 本地通知API + + window.plugins.jPushPlugin.addLocalNotification(builderId, + content, + title, + notificaitonID, + broadcastTime, + extras) + window.plugins.jPushPlugin.removeLocalNotification(notificationID) + window.plugins.jPushPlugin.clearLocalNotifications() + +[Android API详细说明](document/Android_detail_api.md) diff --git a/document/Android_detail_api.md b/document/Android_detail_api.md new file mode 100644 index 0000000..55bae27 --- /dev/null +++ b/document/Android_detail_api.md @@ -0,0 +1,270 @@ +## adnroid API简介 + + +### 停止与恢复推送服务 API +#### API - init + +调用此API,用来开启 +JPush SDK 提供的推送服务。 + +开发者App可以通过调用停止推送服务API来停止极光推送服务。当又需要使用极光推送服务时，则必须要调用恢复推送服务 API。 + +``` +本功能是一个完全本地的状态操作。也就是说：停止推送服务的状态不会保存到服务器上。 + +如果停止推送服务后，开发者App被重新安装，或者被清除数据， + +JPush SDK 会恢复正常的默认行为。（因为保存在本地的状态数据被清除掉了）。 +本功能其行为类似于网络中断的效果，即：推送服务停止期间推送的消息， + +恢复推送服务后，如果推送的消息还在保留的时长范围内，则客户端是会收到离线消息。 +``` + +##### 接口定义 + + window.plugins.jPushPlugin.init() + +#### API - stopPush ++ 在android平台 + + + 开发者App可以通过调用停止推送服务API来停止极光推送服务。当又需要使用极光推送服务时，则必须要调用恢复推送服务 API。 + + + + 调用了本 API 后，JPush 推送服务完全被停止。具体表现为： + + + JPush Service 不在后台运行 + + 收不到推送消息 + + 不能通过 JPushInterface.init 恢复，需要调用resumePush恢复 + + 极光推送所有的其他 API 调用都无效 + ++ iOS平台 + + + 不推荐调用，因为这个API只是让你的DeviceToken失效，在设置－通知 中您的应用程序没有任何变化 + + 推荐：设置一个UI界面， 提醒用户在在设置－通知关闭推送服务 + +##### 接口定义 + + window.plugins.jPushPlugin.stopPush() + +#####平台 +android，iOS + +#### API - resumePush + +恢复推送服务。 +调用了此 API 后，在android平台上极光推送完全恢复正常工作，在iOS平台上重新去APNS注册 + +#####平台 +android iOS + +##### 接口定义 + + window.plugins.jPushPlugin.resumePush() + +#### API - isPushStopped + +在android 用来检查 Push Service 是否已经被停止 +在iOS 平台检查推送服务是否注册 + +##### 接口定义 + + window.plugins.jPushPlugin.isPushStopped(callback) + +#####平台 +android iOS + +##### 参数说明 + ++ callback 回调函数，用来通知JPush的推送服务是否开启 + +####代码示例 + window.plugins.jPushPlugin.resumePush(callback) + var onCallback = function(data) { + if(data>0){ + //开启 + }else{ + //关闭 + } + } + +### 获取集成日志 + +#### API - setDebugMode + +用于开启调试模式，可以查看集成JPush过程中的log，如果集成失败，可方便定位问题所在 + +##### 接口定义 + + window.plugins.jPushPlugin.setDebugMode (mode) + +##### 参数说明 + +- mode的值 + + - true 显示集成日志 + - false 不显示集成日志 + + +### 接收推送消息Receiver +#### API - receiveMessageInAndroidCallback + +用于android收到应用内消息的回调函数(请注意和通知的区别)，该函数不需要主动调用 + +##### 接口定义 + + window.plugins.jPushPlugin.receiveMessageInAndroidCallback = function(data) + +##### 参数说明 +- data 接收到的js字符串，包含的key:value请进入该函数体查看 + +##### 代码示例 + +#### API - openNotificationInAndroidCallback + +当点击android手机的通知栏进入应用程序时,会调用这个函数，这个函数不需要主动调用，是作为回调函数来用的 + + +##### 接口定义 + + window.plugins.jPushPlugin.openNotificationInAndroidCallback = function(data) + +##### 参数说明 +- data js字符串 + +##### 代码示例 + +### 统计分析 API + +#### API - onResume / onPause +这是一个 android local api，不是js的api，请注意 +本 API 用于“用户使用时长”，“活跃用户”，“用户打开次数”的统计，并上报到服务器，在 Portal 上展示给开发者。 + + + +####接口定义 + + public static void onResume(final Activity activity) + public static void onPause(final Activity activity) +####参数说明 + + ＋ Activity activity 当前所在的Activity。 +####调用说明 + +应在所有的 Activity 的 onResume / onPause 方法里调用。 + +####代码示例 + + @Override + protected void onResume() { + super.onResume(); + JPushInterface.onResume(this); + } + @Override + protected void onPause() { + super.onPause(); + JPushInterface.onPause(this); + } + + +#### API - reportNotificationOpened + +用于上报用户的通知栏被打开，或者用于上报用户自定义消息被展示等客户端需要统计的事件。 + + +##### 接口定义 + + window.plugins.jPushPlugin.reportNotificationOpened(msgID) + +##### 参数说明 +- msgID + -收到的通知或者自定义消息的id + + +### 清除通知 API + +#### API - clearAllNotification + +推送通知到客户端时，由 JPush SDK 展现通知到通知栏上。 + +此 API 提供清除通知的功能，包括：清除所有 JPush 展现的通知（不包括非 JPush SDK 展现的） + + +##### 接口定义 + + window.plugins.jPushPlugin.clearAllNotification = function() + +### 设置允许推送时间 API +### 设置通知静默时间 API +### 通知栏样式定制 API + +#### API - setBasicPushNotificationBuilder,setCustomPushNotificationBuilder + +当用户需要定制默认的通知栏样式时，则可调用此方法。 +极光 Push SDK 提供了 2 个用于定制通知栏样式的构建类： + +- setBasicPushNotificationBuilder + - Basic 用于定制 Android Notification 里的 defaults / flags / icon 等基础样式（行为） +- setCustomPushNotificationBuilder + - 继承 Basic 进一步让开发者定制 Notification Layout + +如果不调用此方法定制，则极光Push SDK 默认的通知栏样式是：Android标准的通知栏提示。 + +##### 接口定义 + + window.plugins.jPushPlugin.setBasicPushNotificationBuilder = function() + window.plugins.jPushPlugin.setCustomPushNotificationBuilder = function() + + +### 设置保留最近通知条数 API + +#### API - setLatestNotificationNum + +通过极光推送，推送了很多通知到客户端时，如果用户不去处理，就会有很多保留在那里。 + +新版本 SDK (v1.3.0) 增加此功能，限制保留的通知条数。默认为保留最近 5 条通知。 + +开发者可通过调用此 API 来定义为不同的数量。 + +##### 接口定义 + + window.plugins.jPushPlugin.setLatestNotificationNum(num) + +##### 参数说明 + +- num 保存的条数 + + +### 本地通知API +#### API - addLocalNotification,removeLocalNotification,clearLocalNotifications + + +本地通知API不依赖于网络，无网条件下依旧可以触发 + +本地通知与网络推送的通知是相互独立的，不受保留最近通知条数上限的限制 + +本地通知的定时时间是自发送时算起的，不受中间关机等操作的影响 + + +三个接口的功能分别为：添加一个本地通知，删除一个本地通知，删除所有的本地通知 + +#####接口定义 + + window.plugins.jPushPlugin.addLocalNotification = function(builderId, + content, + title, + notificaitonID, + broadcastTime, + extras) + window.plugins.jPushPlugin.removeLocalNotification = function(notificationID) + window.plugins.jPushPlugin.clearLocalNotifications = function() + +##### 参数说明 + +- builderId 设置本地通知样式 +- content 设置本地通知的content +- title 设置本地通知的title +- notificaitonID 设置本地通知的ID +- broadcastTime 设置本地通知触发时间，为距离当前时间的数值，单位是毫秒 +- extras 设置额外的数据信息extras为json字符串 + + diff --git a/document/android_auto_install.md b/document/Android_handle_install.md similarity index 99% rename from document/android_auto_install.md rename to document/Android_handle_install.md index 0f20299..68ae2d3 100644 --- a/document/android_auto_install.md +++ b/document/Android_handle_install.md @@ -1,4 +1,5 @@ -###Android 手工安装### +#Android 手工安装 + 1. 复制src/android/*.java 到cn/jpush/phonega/目录下(即：cn.jpush.phonegap的包下) 2. 复制src/android/armeabi/libjpush.so 到lib/armeabi/ 3. 复制src/android/jpush-sdk-release1.5.0.jar 到lib/ diff --git a/document/Common_detail_api.md b/document/Common_detail_api.md new file mode 100644 index 0000000..706ea12 --- /dev/null +++ b/document/Common_detail_api.md @@ -0,0 +1,121 @@ +#通用API说明 + +##获取 RegistrationID API +### API - getRegistrationID + +RegistrationID 定义 + +集成了 JPush SDK 的应用程序在第一次成功注册到 JPush 服务器时，JPush 服务器会给客户端返回一个唯一的该设备的标识 - RegistrationID。JPush SDK 会以广播的形式发送 RegistrationID 到应用程序。 + +应用程序可以把此 RegistrationID 保存以自己的应用服务器上，然后就可以根据 RegistrationID 来向设备推送消息或者通知。 + +#### 接口定义 + + JPushPlugin.prototype.getRegistrationID = function(callback) + +##### 参数说明 +无 +#### 返回值 + +调用此 API 来取得应用程序对应的 RegistrationID。 只有当应用程序成功注册到 JPush 的服务器时才返回对应的值，否则返回空字符串。 + +#### 调用示例 + + window.plugins.jPushPlugin.getRegistrationID(onGetRegistradionID); + var onGetRegistradionID = function(data) { + try{ + console.log("JPushPlugin:registrationID is "+data) } + catch(exception){ + console.log(exception); + } + } + +##别名与标签 API + +### API - setTagsWithAlias,setTags,setAlias + +提供几个相关 API 用来设置别名（alias）与标签（tags）。 + +这几个 API 可以在 App 里任何地方调用。 + +别名 alias + +为安装了应用程序的用户，取个别名来标识。以后给该用户 Push 消息时，就可以用此别名来指定。 + +每个用户只能指定一个别名。 + +同一个应用程序内，对不同的用户，建议取不同的别名。这样，尽可能根据别名来唯一确定用户。 + +系统不限定一个别名只能指定一个用户。如果一个别名被指定到了多个用户，当给指定这个别名发消息时，服务器端API会同时给这多个用户发送消息。 + +举例：在一个用户要登录的游戏中，可能设置别名为 userid。游戏运营时，发现该用户 3 天没有玩游戏了，则根据 userid 调用服务器端API发通知到客户端提醒用户。 + +标签 tag + +为安装了应用程序的用户，打上标签。其目的主要是方便开发者根据标签，来批量下发 Push 消息。 + +可为每个用户打多个标签。 + +不同应用程序、不同的用户，可以打同样的标签。 + +举例： game, old_page, women + +#### 接口定义 + + JPushPlugin.prototype.setTagsWithAlias = function(tags,alias) + JPushPlugin.prototype.setTags = function(tags) + JPushPlugin.prototype.setAlias = function(alias) + +####使用平台 +android iOS + + +#### 参数说明 +* tags + * 参数类型为数组 + * nil 此次调用不设置此值 + * 空集合表示取消之前的设置 + * 每次调用至少设置一个 tag，覆盖之前的设置，不是新增 + * 有效的标签组成：字母（区分大小写）、数字、下划线、汉字 + * 限制：每个 tag 命名长度限制为 40 字节，最多支持设置 100 个 tag，但总长度不得超过1K字节。（判断长度需采用UTF-8编码） + * 单个设备最多支持设置 100 个 tag。App 全局 tag 数量无限制。 +* alias + * 参数类型为字符串 + * nil 此次调用不设置此值 + * 空字符串 （""）表示取消之前的设置 + * 有效的别名组成：字母（区分大小写）、数字、下划线、汉字。 + * 限制：alias 命名长度限制为 40 字节。（判断长度需采用UTF-8编码） + +#### 返回值说明 + +函数本身无返回值，但需要注册`jpush.setTagsWithAlias `事件来监听设置结果 + + document.addEventListener("jpush.setTagsWithAlias", onTagsWithAlias, false); + var onTagsWithAlias = function(event){ + try{ + console.log("onTagsWithAlias"); + var result="result code:"+event.resultCode+" "; + result+="tags:"+event.tags+" "; + result+="alias:"+event.alias+" "; + $("#tagAliasResult").html(result); + } + catch(exception){ + console.log(exception) + } + } + +####错误码定义 + + +|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 字节| +|6011| 10s内设置tag或alias大于3次| 短时间内操作过于频繁| + diff --git a/document/iOS_detail_api.md b/document/iOS_detail_api.md new file mode 100644 index 0000000..d184cdd --- /dev/null +++ b/document/iOS_detail_api.md @@ -0,0 +1,176 @@ +## iOS API简介 + +### 获取 APNs（通知） 推送内容 + +#### event - jpush.receiveNotification + +当iOS收到的通知时会触发这个事件 + + +#####代码示例 + +- 在你需要接收通知的的js文件中加入: + + document.addEventListener("jpush.receiveNotification", onReceiveNotification, false); + +- onOpenNotification需要这样写： + + var onReceiveNotification = function(event){ + try{ + var alert = event.aps.alert; + console.log("JPushPlugin:onReceiveNotification key aps.alert:"+alert); + } + catch(exeption){ + console.log(exception) + } + } + +#### event - jpush.openNotification + +点击通知进入应用程序时会出发改事件 + +#####代码示例 + +- 在你需要接收通知的的js文件中加入: + + document.addEventListener("jpush.openNotification", onOpenNotification, false); + +- onOpenNotification需要这样写： + + var onOpenNotification = function(event){ + try{ + + var alert = event.aps.alert; + console.log("JPushPlugin:onPpenNotification key aps.alert:"+alert); + } + catch(exception){ + console.log("JPushPlugin:onPpenNotification"+exception); + } + } + + + + +### 获取自定义消息推送内容 + +#### API - receiveMessageIniOSCallback + +用于iOS收到应用内消息的回调函数(请注意和通知的区别)，该函数不需要主动调用 + +##### 接口定义 + + JPushPlugin.prototype.receiveMessageIniOSCallback = function(data) + +#####参数说明 + +- data 是一个js字符串使用如下代码解析，js具体key根据应用内消息来确定 + + var bToObj = JSON.parse(data); + +#####返回值 +无 + +##### 代码示例 + + +### 页面的统计 +#### API - startLogPageView,stopLogPageView,beginLogPageView + +本 API 用于“用户指定页面使用时长”的统计，并上报到服务器，在 Portal 上展示给开发者。页面统计集成正确，才能够获取正确的页面访问路径、访问深度（PV）的数据。 + +##### 接口定义 + JPushPlugin.prototype.startLogPageView = function(pageName) + JPushPlugin.prototype.stopLogPageView = function(pageName) + JPushPlugin.prototype.beginLogPageView = function(pageName,duration) +#####参数说明 +pageName 需要统计页面自定义名称 +duration 自定义的页面时间 +#####调用说明 +应在所有的需要统计得页面得 viewWillAppear 和 viewWillDisappear 加入 startLogPageView 和 stopLogPageView 来统计当前页面的停留时间。 + + 或者直接使用 beginLogPageView 来自定义加入页面和时间信息。 +#####返回值说明 +无 +#####代码示例 + + if(window.plugins.jPushPlugin.isPlatformIOS()){ + window.plugins.jPushPlugin.beginLogPageView("newPage",5); + window.plugins.jPushPlugin.startLogPageView("onePage"); + window.plugins.jPushPlugin.stopLogPageView("onePage"); + } +### 设置Badge +#### API - setBadge,resetBadge + +badge是iOS用来标记应用程序状态的一个数字，出现在程序图标右上角。 JPush封装badge功能，允许应用上传badge值至JPush服务器，由JPush后台帮助管理每个用户所对应的推送badge值，简化了设置推送badge的操作。 + +实际应用中，开发者可以直接对badge值做增减操作，无需自己维护用户与badge值之间的对应关系。 +##### 接口定义 + + JPushPlugin.prototype.setBadge = function(value) + JPushPlugin.prototype.resetBadge = function() + +`resetBadge相当于setBadge(0)` +##### 参数说明 +value 取值范围：[0,99999] +##### 返回值 +无，控制台会有log打印设置结果 +#####代码示例 + + if(window.plugins.jPushPlugin.isPlatformIOS()){ + window.plugins.jPushPlugin.setBadge(5); + window.plugins.jPushPlugin.reSetBadge(); + } + +#### API - setApplicationIconBadgeNumber + +设置iOS的角标，当设置badge＝0时为清除角标 + +##### 接口定义 + + JPushPlugin.prototype.setApplicationIconBadgeNumber = function(badge) + +##### 参数说明 + +- badge 整形,例如0，1，2 +- 当badge为0时，角标被清除 + +#####代码示例 + + if(window.plugins.jPushPlugin.isPlatformIOS()){ + JPushPlugin.prototype.setApplicationIconBadgeNumber(0); + } + + +### 本地通知 + +### 日志等级设置 +#### API - setDebugModeFromIos +API 用于开启Debug模式，显示更多的日志信息 + +建议调试时开启这个选项，不调试的时候注释这句代码，这个函数setLogOFF是相反的一对 +##### 接口定义 + + JPushPlugin.prototype.setDebugModeFromIos = function() + +#####代码示例 + + if(window.plugins.jPushPlugin.isPlatformIOS()){ + window.plugins.jPushPlugin.setDebugModeFromIos(); + } + +#### API - setLogOFF + +API用来关闭日志信息（除了必要的错误信息） + +不需要任何调试信息的时候，调用此API （发布时建议调用此API，用来屏蔽日志信息，节省性能消耗) + +##### 接口定义 + + JPushPlugin.prototype.setLogOFF = function() + +#####代码示例 + + if(window.plugins.jPushPlugin.isPlatformIOS()){ + window.plugins.jPushPlugin.setLogOFF(); + } + diff --git a/document/iOS_handle_install.md b/document/iOS_handle_install.md new file mode 100644 index 0000000..48ae36c --- /dev/null +++ b/document/iOS_handle_install.md @@ -0,0 +1,72 @@ +### IOS手工安装 + +1. 添加src/ios/Plugins/到project中 +2. 添加src/ios/lib/到project中 +3. 设置 Search Paths 下的 User Header Search Paths 和 Library Search Paths + +比如SDK文件夹（默认为lib）与工程文件在同一级目录下，则都设置为"$(SRCROOT)/[文件夹名称]"即可。 + +4. 确认一下的框架是存在的(Target -> Build Phases -> Link Binary With Libraries) + + CFNetwork.framework + CoreFoundation.framework + CoreTelephony.framework + SystemConfiguration.framework + CoreGraphics.framework + Foundation.framework + UIKit.framework + + +5. 在你的工程中创建一个新的Property List文件 + + 并将其命名为PushConfig.plist，填入Portal为你的应用提供的APP_KEY等参数 + + +6. 调用代码,监听系统事件，相应地调用 JPush SDK 提供的 API 来实现功能 + + - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions + { + #if __has_feature(objc_arc) + self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]]; + #else + self.window = [[[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]] autorelease]; + #endif + self.window.backgroundColor = [UIColor whiteColor]; + [self.window makeKeyAndVisible]; + + // Required + [APService registerForRemoteNotificationTypes:(UIRemoteNotificationTypeBadge | + UIRemoteNotificationTypeSound | + UIRemoteNotificationTypeAlert)]; + // Required + [APService setupWithOption:launchOptions]; + + return YES; + } + + - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken { + + // Required + [APService registerDeviceToken:deviceToken]; + } + + - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo { + + // Required + [APService handleRemoteNotification:userInfo]; + } + + +7. 修改phonegap config.xml文件用来包含Plugin/内的插件 + + + + + + + + +8. 复制www/PushNotification.js到工程的www目录下面 +9. 在需要使用插件处加入 + + diff --git a/src/ios/Plugins/JPushPlugin.m b/src/ios/Plugins/JPushPlugin.m index 6dd503d..08c154b 100644 --- a/src/ios/Plugins/JPushPlugin.m +++ b/src/ios/Plugins/JPushPlugin.m @@ -34,9 +34,11 @@ static NSDictionary *_luanchOptions=nil; name:kJPushPluginReceiveNotification object:nil]; + if (!_luanchOptions) { + return; + } NSDictionary *userInfo = [_luanchOptions - valueForKey:UIApplicationLaunchOptionsRemoteNotificationKey]; - + valueForKey:UIApplicationLaunchOptionsRemoteNotificationKey]; if (_luanchOptions && [userInfo count] >0) { NSError *error; NSData *jsonData = [NSJSONSerialization dataWithJSONObject:userInfo options:0 error:&error]; @@ -49,10 +51,24 @@ static NSDictionary *_luanchOptions=nil; } } + } return self; } +-(void)init:(CDVInvokedUrlCommand*)command{ + if (!_luanchOptions) { + NSLog("must set [JPushPlugin setLaunchOptions:launchOptions] in AppDelegate.m"): + return; + } + [APService registerForRemoteNotificationTypes:(UIUserNotificationTypeBadge | + UIUserNotificationTypeSound | + UIUserNotificationTypeAlert) + categories:nil]; + [APService setupWithOption:_luanchOptions]; + +} + -(void)setTagsWithAlias:(CDVInvokedUrlCommand*)command{ NSArray *arguments=command.arguments; diff --git a/www/JPushPlugin.js b/www/JPushPlugin.js index d84f274..bcae17a 100644 --- a/www/JPushPlugin.js +++ b/www/JPushPlugin.js @@ -258,18 +258,6 @@ JPushPlugin.prototype.clearLocalNotifications = function(){ this.call_native("clearLocalNotifications",data,null); } } -JPushPlugin.prototype.onResume = function(){ - if(device.platform == "Android") { - data=[] - this.call_native("onResume",data,null); - } -} -JPushPlugin.prototype.onPause = function(){ - if(device.platform == "Android") { - data=[] - this.call_native("onPause",data,null); - } -} JPushPlugin.prototype.reportNotificationOpened = function(msgID){ if(device.platform == "Android") {