From 4e0cf44414ef8fee32757a132c31961fa5e33c9e Mon Sep 17 00:00:00 2001
From: huangminlinux <380108184@qq.com>
Date: Sat, 29 Sep 2018 12:01:18 +0800
Subject: [PATCH] update docs

---
 README.md              |   3 +-
 documents/APIs.md      | 200 +++++++++++++++++++++++++++++++++++++++++
 example/lib/main.dart  |  69 ++++++--------
 lib/jpush_flutter.dart |   6 +-
 4 files changed, 232 insertions(+), 46 deletions(-)
 create mode 100644 documents/APIs.md

diff --git a/README.md b/README.md
index 5ac1667..8d452f6 100644
--- a/README.md
+++ b/README.md
@@ -51,4 +51,5 @@ import 'package:jpush_flutter/jpush_flutter.dart';
 
 **注意** : 需要先调用 JPush.setup 来初始化插件，才能保证其他功能正常工作。
 
- [参考](./lib/jpush_flutter.dart)
+ [参考](./documents/APIs.md)
+
diff --git a/documents/APIs.md b/documents/APIs.md
new file mode 100644
index 0000000..9a35e3a
--- /dev/null
+++ b/documents/APIs.md
@@ -0,0 +1,200 @@
+[Common API](#common-api)
+
+- [addEventHandler](#addeventhandler)
+- [setup](#setup)
+- [getRegistrationID](#getregistrationid)
+- [stopPush](#stoppush)
+- [resumePush](#resumepush)
+- [setAlias](#setalias)
+- [deleteAlias](#deletealias)
+- [addTags](#addtags)
+- [deleteTags](#deletetags)
+- [setTags](#settags)
+- [cleanTags](#cleantags)
+- [getAllTags](getalltags)
+- [sendLocalNotification](#sendlocalnotification)
+- [clearAllNotifications](#clearallnotifications)
+
+[iOS Only]()
+
+- [applyPushAuthority](#applypushauthority)
+- [setBadge](#setbadge)
+- [getLaunchAppNotification](#getlaunchappnotification)
+
+**注意：addEventHandler 方法建议放到 setup 之前，其他方法需要在 setup 方法之后调用，**
+
+####  addEventHandler
+
+添加事件监听方法。
+
+```dart
+JPush.addEventHandler(
+      // 接收通知回调方法。
+      onReceiveNotification: (Map<String, dynamic> message) async {
+         print("flutter onReceiveNotification: $message");
+      },
+      // 点击通知回调方法。
+      onOpenNotification: (Map<String, dynamic> message) async {
+        print("flutter onOpenNotification: $message");
+      },
+      // 接收自定义消息回调方法。
+      onReceiveMessage: (Map<String, dynamic> message) async {
+        print("flutter onReceiveMessage: $message");
+      },
+  );
+```
+
+#### setup
+
+添加初始化方法，调用 setup 方法会执行两个操作：
+
+- 初始化 JPush SDK
+- 将缓存的事件下发到 dart 环境中。
+
+```dart
+JPush.setup(
+      appKey: "替换成你自己的 appKey",
+      channel: "theChannel",
+      production: false
+    );
+```
+
+#### getRegistrationID
+
+获取 registrationId，这个 JPush 运行通过 registrationId 来进行推送.
+
+```dart
+JPush.getRegistrationID().then((rid) { });
+```
+
+#### stopPush
+
+停止推送功能，调用该方法将不会接收到通知。
+
+```dart
+JPush.stopPush();
+```
+
+#### resumePush
+
+调用 stopPush 后，可以通过 resumePush 方法恢复推送。
+
+```dart
+JPush.resumePush();
+```
+
+#### setAlias
+
+设置别名，极光后台可以通过别名来推送，一个 App 应用只有一个别名，一般用来存储用户 id。
+
+```
+JPush.setAlias("your alias").then((map) { });
+```
+
+#### deleteAlias
+
+可以通过 deleteAlias 方法来删除已经设置的 alias。
+
+```dart
+JPush.deleteAlias().then((map) {})
+```
+
+#### addTags
+
+在原来的 Tags 列表上添加指定 tags。
+
+```
+JPush.addTags(["tag1","tag2"]).then((map) {});
+```
+
+####  deleteTags
+
+在原来的 Tags 列表上删除指定 tags。
+
+```
+JPush.deleteTags(["tag1","tag2"]).then((map) {});
+```
+
+#### setTags
+
+重置 tags。
+
+```
+JPush.setTags(["tag1","tag2"]).then((map) {});
+```
+
+#### cleanTags
+
+清空所有 tags
+
+```dart
+JPush.setTags().then((map) {});
+```
+
+#### getAllTags
+
+获取当前 tags 列表。
+
+```
+JPush.getAllTags().then((map) {});
+```
+
+#### sendLocalNotification
+
+指定触发时间，添加本地推送通知。
+
+```dart
+// 延时 3 秒后触发本地通知。
+var fireDate = DateTime.fromMillisecondsSinceEpoch(DateTime.now().millisecondsSinceEpoch + 3000);
+var localNotification = LocalNotification(
+   id: 234,
+   title: 'notification title',
+   buildId: 1,
+   content: 'notification content',
+   fireTime: fireDate,
+   subtitle: 'notification subtitle', // 该参数只有在 iOS 有效
+   badge: 5, // 该参数只有在 iOS 有效
+   extras: {"fa": "0"} // 设置 extras ，extras 需要是 Map<String, String>
+  );
+JPush.sendLocalNotification(localNotification).then((res) {});
+```
+
+#### clearAllNotifications
+
+清楚通知栏上所有通知。
+
+```dart
+JPush.clearAllNotifications();
+```
+
+#### applyPushAuthority
+
+申请推送权限，注意这个方法只会向用户弹出一次推送权限请求（如果用户不同意，之后只能用户到设置页面里面勾选相应权限），需要开发者选择合适的时机调用。
+
+**注意： iOS10+ 可以通过该方法来设置推送是否前台展示，是否触发声音，是否设置应用角标 badge**
+
+```dart
+JPush.applyPushAuthority(new NotificationSettingsIOS(
+      sound: true,
+      alert: true,
+      badge: true));
+```
+
+#### setBadge
+
+**iOS Only **
+
+设置应用 badge 值，该方法还会同步 JPush 服务器的的 badge 值，JPush 服务器的 badge 值用于推送 badge 自动 +1 时会用到。
+
+```dart
+JPush.setBadge(66).then((map) {});
+```
+
+### getLaunchAppNotification
+
+获取 iOS 点击推送启动应用的那条通知。
+
+```dart
+JPush.getLaunchAppNotification().then((map) {});
+```
+
diff --git a/example/lib/main.dart b/example/lib/main.dart
index ee68dd7..8f7eda3 100644
--- a/example/lib/main.dart
+++ b/example/lib/main.dart
@@ -12,7 +12,7 @@ class MyApp extends StatefulWidget {
 }
 
 class _MyAppState extends State<MyApp> {
-  String _platformVersion = 'Unknown';
+  String debugLable = 'Unknown';
 
   @override
   void initState() {
@@ -25,9 +25,9 @@ class _MyAppState extends State<MyApp> {
     String platformVersion;
     // Platform messages may fail, so we use a try/catch PlatformException.
     JPush.getRegistrationID().then((rid) {
-      // setState(() {
-      //     _platformVersion = "flutter getRegistrationID: $rid";
-      //   });
+      setState(() {
+          debugLable = "flutter getRegistrationID: $rid";
+        });
     });
 
     JPush.setup(
@@ -52,7 +52,7 @@ class _MyAppState extends State<MyApp> {
       onOpenNotification: (Map<String, dynamic> message) async {
         print("flutter onOpenNotification: $message");
         setState(() {
-            _platformVersion = "flutter onOpenNotification: $message";
+            debugLable = "flutter onOpenNotification: $message";
           });
       },
       onReceiveMessage: (Map<String, dynamic> message) async {
@@ -60,10 +60,7 @@ class _MyAppState extends State<MyApp> {
         
       },
       );
-      print("lalallalalal");
 
-      // platformVersion = await JPush.platformVersion;
-      // platformVersion = "$platformVersion fadfa";
     } on PlatformException {
       platformVersion = 'Failed to get platform version.';
     }
@@ -74,7 +71,7 @@ class _MyAppState extends State<MyApp> {
     if (!mounted) return;
 
     setState(() {
-      _platformVersion = platformVersion;
+      debugLable = platformVersion;
     });
   }
 
@@ -91,19 +88,10 @@ class _MyAppState extends State<MyApp> {
         body: new Center(
           child: new Column(
             children:[
-              new Text('result: $_platformVersion\n'), 
+              new Text('result: $debugLable\n'), 
               new FlatButton(
               child: new Text('sendLocalNotification\n'), 
               onPressed: () {
-                    // @require this.id,
-                    // @require this.title,
-                    // @require this.content,
-                    // @require this.fireTime,
-                    // this.buildId,
-                    // this.extras,
-                    // this.badge,
-                    // this.soundName,
-                    // this.subtitle
                 // 三秒后出发本地推送
                 var fireDate = DateTime.fromMillisecondsSinceEpoch(DateTime.now().millisecondsSinceEpoch + 3000);
                 var localNotification = LocalNotification(
@@ -118,7 +106,7 @@ class _MyAppState extends State<MyApp> {
                   );
                 JPush.sendLocalNotification(localNotification).then((res) {
                   setState(() {
-                      _platformVersion = res;
+                      debugLable = res;
                     });
                 });
 
@@ -135,12 +123,12 @@ class _MyAppState extends State<MyApp> {
                   JPush.setTags(["lala","haha"]).then((map) {
                     var tags = map['tags'];
                     setState(() {
-                      _platformVersion = "set tags success: $map $tags";
+                      debugLable = "set tags success: $map $tags";
                     });
                   })
                   .catchError((error) {
                     setState(() {
-                      _platformVersion = "set tags error: $error";
+                      debugLable = "set tags error: $error";
                     });
                   }) ;
                 }),
@@ -150,12 +138,12 @@ class _MyAppState extends State<MyApp> {
                     JPush.cleanTags().then((map) {
                     var tags = map['tags'];
                     setState(() {
-                      _platformVersion = "cleanTags success: $map $tags";
+                      debugLable = "cleanTags success: $map $tags";
                     });
                   })
                   .catchError((error) {
                     setState(() {
-                      _platformVersion = "cleanTags error: $error";
+                      debugLable = "cleanTags error: $error";
                     });
                   }) ;
               }),
@@ -166,12 +154,12 @@ class _MyAppState extends State<MyApp> {
                     JPush.addTags(["lala","haha"]).then((map) {
                     var tags = map['tags'];
                     setState(() {
-                      _platformVersion = "addTags success: $map $tags";
+                      debugLable = "addTags success: $map $tags";
                     });
                   })
                   .catchError((error) {
                     setState(() {
-                      _platformVersion = "addTags error: $error";
+                      debugLable = "addTags error: $error";
                     });
                   }) ;
 
@@ -183,12 +171,12 @@ class _MyAppState extends State<MyApp> {
                   JPush.deleteTags(["lala","haha"]).then((map) {
                     var tags = map['tags'];
                     setState(() {
-                      _platformVersion = "deleteTags success: $map $tags";
+                      debugLable = "deleteTags success: $map $tags";
                     });
                   })
                   .catchError((error) {
                     setState(() {
-                      _platformVersion = "deleteTags error: $error";
+                      debugLable = "deleteTags error: $error";
                     });
                   }) ;
 
@@ -199,12 +187,12 @@ class _MyAppState extends State<MyApp> {
                   
                   JPush.getAllTags().then((map) {
                     setState(() {
-                      _platformVersion = "getAllTags success: $map";
+                      debugLable = "getAllTags success: $map";
                     });
                   })
                   .catchError((error) {
                     setState(() {
-                      _platformVersion = "getAllTags error: $error";
+                      debugLable = "getAllTags error: $error";
                     });
                   }) ;
 
@@ -215,12 +203,12 @@ class _MyAppState extends State<MyApp> {
                   
                   JPush.setAlias("thealias11").then((map) {
                     setState(() {
-                      _platformVersion = "setAlias success: $map";
+                      debugLable = "setAlias success: $map";
                     });
                   })
                   .catchError((error) {
                     setState(() {
-                      _platformVersion = "setAlias error: $error";
+                      debugLable = "setAlias error: $error";
                     });
                   }) ;
 
@@ -231,12 +219,12 @@ class _MyAppState extends State<MyApp> {
                   
                   JPush.deleteAlias().then((map) {
                     setState(() {
-                      _platformVersion = "deleteAlias success: $map";
+                      debugLable = "deleteAlias success: $map";
                     });
                   })
                   .catchError((error) {
                     setState(() {
-                      _platformVersion = "deleteAlias error: $error";
+                      debugLable = "deleteAlias error: $error";
                     });
                   }) ;
 
@@ -247,12 +235,12 @@ class _MyAppState extends State<MyApp> {
                   
                   JPush.setBadge(66).then((map) {
                     setState(() {
-                      _platformVersion = "setBadge success: $map";
+                      debugLable = "setBadge success: $map";
                     });
                   })
                   .catchError((error) {
                     setState(() {
-                      _platformVersion = "setBadge error: $error";
+                      debugLable = "setBadge error: $error";
                     });
                   }) ;
 
@@ -284,12 +272,12 @@ class _MyAppState extends State<MyApp> {
                   
                   JPush.getLaunchAppNotification().then((map) {
                     setState(() {
-                      _platformVersion = "getLaunchAppNotification success: $map";
+                      debugLable = "getLaunchAppNotification success: $map";
                     });
                   })
                   .catchError((error) {
                     setState(() {
-                      _platformVersion = "getLaunchAppNotification error: $error";
+                      debugLable = "getLaunchAppNotification error: $error";
                     });
                   });
 
@@ -297,10 +285,7 @@ class _MyAppState extends State<MyApp> {
                 
             ]
           )
-          // new Text('Running on: $_platformVersion\n'),
-          // child: new FlatButton(onPressed: () => {
-
-          // }),
+          
         ),
       ),
     );
diff --git a/lib/jpush_flutter.dart b/lib/jpush_flutter.dart
index a3adf8b..e2d9335 100644
--- a/lib/jpush_flutter.dart
+++ b/lib/jpush_flutter.dart
@@ -1,5 +1,5 @@
 import 'dart:async';
-
+import 'package:flutter/foundation.dart';
 import 'package:flutter/services.dart';
 import 'dart:io' show Platform;
 
@@ -54,7 +54,7 @@ class JPush {
     }
 
     ///
-    /// 申请推送权限当，注意这个方法只会向用户弹出一次推送权限请求（如果用户不同意，之后只能用户到设置页面里面勾选相应权限），需要开发者选择合适的时机调用。
+    /// 申请推送权限，注意这个方法只会向用户弹出一次推送权限请求（如果用户不同意，之后只能用户到设置页面里面勾选相应权限），需要开发者选择合适的时机调用。
     ///
     static void applyPushAuthority([NotificationSettingsIOS iosSettings = const NotificationSettingsIOS()]) {
 
@@ -251,7 +251,7 @@ class LocalNotification {
   final int id;
   final String title;
   final String content;
-  final Map<String, dynamic> extras;//?
+  final Map<String, String> extras;//?
   final DateTime fireTime;
   final int badge;//?
   final String soundName;//?