SDK 简介

MaxLeap RN SDK 包括一系列的基础包和一些开源 UI 组件。

1 详细介绍

1.1 maxleap-react-native npm version

核心包,MaxLeap 的很多其它 SDK 都依赖于它。

集成指南

MaxLeap.framework 内置功能以及使用指南:

1.2 maxpay-react-native npm version

从 Native SDK 导出的支付接口,集成指南

1.3 maxleap-social-react-native npm version

从 Native SDK 导出的应用内社交接口,集成指南

1.4 maxlogin-react-native npm version

简单易用的 登录/注册/手机号登录 界面。开源组件地址:https://github.com/MaxLeap/Module-MaxLogin-RN

1.5 maxshare-react-native npm version

分享内容到第三方社交平台,目前支持分享到QQ好友,QQ空间,微信好友,微信朋友圈,新浪微博。

集成指南

1.6 maxleap-helpcenter-react-native npm version

由 Native SDK 导出的接口,包含 FAQ 和 Issues 两个模块。

集成指南

1.7 maxleap-im npm version

即时通信的 SDK,网页环境和 ReactNative 环境通用。

集成指南

SDK 集成

MaxLeap SDK RN npm version

创建 MaxLeap 应用

  1. 进入 MaxLeap 注册并登录,然后在 云数据 创建class,这里创建一个Post class。

    注意:SDK 没有创建 / 删除 class 的权限,所以要先在 云数据 中创建好需要用到的 class。

  2. 进入 我的应用-应用设置-应用密钥 复制 Application ID,Client Key。

创建 react-native 项目

$ react-native init Demo

详细信息请参考 React Native 入门

安装 SDK

cd Demo
npm install --save maxleap-react-native

集成 iOS 环境

  1. 打开 Finder, 导航到当前项目根目录,进入 node_modules/maxleap-react-native/ios/lib 文件夹,把这个文件夹下的 frameworks 都添加到 Xcode 工程中。
  2. 在弹出的对话框中的 Added folders 选项上选择 Create groups,点击 Finish
  3. 添加依赖 确保“Enable Modules (C and Objective-C)” 和 “Link Frameworks Automatically”的生成设置为 Yes。

    点击 Targets → YourAppName → “Build Phases” 栏。
    展开 “Link Binary With Libraries”

    点击 “Link Binary With Libraries” 左下角+号按钮,添加下列框架:

    MobileCoreServices.framework
    CoreTelephony.framework
    SystemConfiguration.framework
    libsqlite3.dylib
    libz.dylib

  4. 添加 Framework Search Paths

    在 Xcode 中,导航到 Targets -> YourAppName -> “Build Settings",找到 “Framework Search Paths” 一项,添加下面这个路径:

    $(SRCROOT)/../node_modules/maxleap-react-native/ios/lib

  5. 修改 AppDelegate.m 文件

    加入以下代码:

    #import <MaxLeap/MaxLeap.h>
    
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
       [MaxLeap setApplicationId:@"your_maxleap_appId" 
                       clientKey:@"your_maxleap_clientKey"
                                site:MLSiteCN];
       // your code ...
    }
    

集成 Android 环境

  1. 修改父工程目录下的 build.gradle 文件(与 settings.gradle 位于同级目录)。

    repositories {
        flatDir{
            dirs '../../node_modules/maxleap-react-native/dist/android'
        }
    }
    
  2. 修改应用目录下的 build.gradle 文件,添加以下依赖

    dependencies {
        compile(name:'maxleap-react-native', ext:'aar')
    }
    
  3. 修改工程的主 Activity 文件。

    import android.os.Bundle;
    import com.maxleap.reactnative.MaxLeap;
    
    private MaxLeap maxLeap;
    
     @Override
    protected void onCreate(Bundle savedInstanceState) {
        // 确保在 super.onCreate() 之前调用以下代码
        maxLeap = new MaxLeap(this, APP_ID, API_KEY);
        super.onCreate(savedInstanceState);
    }
    
    @Override
    protected List<ReactPackage> getPackages() {
        return Arrays.<ReactPackage>asList(
                new MainReactPackage(),
                maxLeap.getReactPackage()
        );
    }
    

开始测试

  1. 注册应用内用户并登录:

    var user = new ML.User();
    user.set('username', 'yourname@example.com');
    user.set('password', 'yourpassword');
    user.set('email', 'yourname@example.com');
    
    user.signUp().then(function (user) {
        alert('success');
    });
    

    注意: 云数据 中的数据操作需要权限认证,所以请确保你在登录状态。

  2. 存储数据:

    var Post = ML.Object.extend('Post');
    post.set('title', 'post title');
    post.save().then(function(){
        alert('success');
    });
    

数据存储

Author: Henry
Github: https://github.com/henryybai

简介

什么是数据存储服务

云数据库是 MaxLeap 提供的数据存储服务,它建立在对象 ML.Object 的基础上,每个 ML.Object 包含若干键值对。所有 ML.Object 均存储在 MaxLeap 上,您可以通过 Javascript SDK 对其进行操作,也可在 Console 中管理所有的对象。此外 MaxLeap 还提供一些特殊的对象,如 ML.User (用户),ML.File (文件),ML.GeoPoint (地理位置),他们都是基于 ML.Object 的对象。

对象

存储在云数据的对象称为 ML.Object,而每个 ML.Object 被规划至不同的 class 中(类似“表”的概念)。ML.Object 包含若干键值对,且值为兼容 JSON 格式的数据。考虑到数据安全,MaxLeap 禁止客户端修改数据仓库的结构。您需要预先在 MaxLeap 开发者平台上创建需要用到的表,然后仔细定义每个表中的字段和其值类型。

新建

假设我们要保存一条数据到 Comment class,它包含以下属性:

属性名值类型
content“我很喜欢这条分享”字符
pubUserId1314520数字
isReadfalse布尔

我们建议您使用驼峰式命名法来命名类名和字段名(如:NameYourclassesLikeThis, nameYourKeysLikeThis),让您的代码看起来整齐美观。

var Comment = ML.Object.extend('Comment');
var comment = new Comment();
comment.set('content', '我很喜欢这条分享');
comment.set('pubUserId', 1314520);
comment.set('isRead', false);

comment.save();

该代码运行后,您可能想知道是否真的执行了相关操作。为确保数据正确保存,您可以在 MaxLeap 开发中心查看应用中的数据。您应该会看到类似于以下的内容:

objectId: "563c154ca5ff7f000168964b", content: "我很喜欢这条分享", pubUserId: 1314520, isRead: false,
createdAt:"2015-11-06T02:49:48.235Z", updatedAt:"2015-11-06T02:49:48.235Z"

注意:

  • Comment表合何时创建: 出于数据安全考虑,MaxLeap 禁止客户端创建表,所以在使用前必须先登录 MaxLeap 的控制台并手动创建 Comment 表。这样在运行代码后这条数据才会被成功插入。
  • 表中同一属性值类型一致: 如果云端的这个应用中已经存在名为 Comment 的数据表,而且也包括 contentpubUserIdisRead 等属性,那么,新建 comment 对象时,对应属性的值的数据类型要和创建该属性时一致,否则保存数据将失败。
  • ML.Object是Schemaless的: 您无需事先指定 ML.Object 存在哪些键,只需在需要的时候增加键值对,后台便会自动储存它们。
  • 内建的属性: 每个 ML.Object 对象有以下几个保存元数据的属性是不需要开发者指定的。这些属性的创建和更新是由系统自动完成的,请不要在代码里使用这些属性来保存数据。

    属性名
    objectId对象的唯一标识符
    createdAt对象的创建时间
    updatedAt对象的最后修改时间
  • 大小限制: ML.Object 的大小被限制在128K以内。

  • 键的名称可以包含英文字母,数字和下划线,但是必须以字母开头。值的类型可为字符, 数字, 布尔, 数组或是 ML.Object,为支持 JSON 编码的类型即可.

  • 您可以在调用 comment.save()时,链式调用 .then(),用以检查新建是否成功。

comment.save().then(function(){
  console.log('success');
}, function(){
  console.log('fail');
});

检索

获取 ML.Object

您可以通过某条数据的 ObjectId,用 ML.Query 获取完整的 ML.Object

var query = new ML.Query(Comment);
query.get('563c154ca5ff7f000168964b').then(function(comment){
  console.log(comment);
});
获取 ML.Object 属性值

为了获得 ML.Object 的属性值,应该使用 get() 方法:

var content = comment.get('content');

更新

更新 ML.Object 需要两步:首先获取需要更新的 ML.Object,然后修改并保存:

var query = new ML.Query(Comment);
query.get('563c154ca5ff7f000168964b').then(function(comment){
  comment.set('isRead', true);

  comment.save().then(function(comment){
    console.log(comment);
  }, function(error){
    console.log(error);
  });
});

删除

删除 ML.Object

调用如下代码会在 MaxLeap 中删除一个实例:

comment.destroy().then(function(result){
//success
}, function(){
//error
});
批量删除

批量删除一批对象可以这样:

ML.Object.destroyAll(objects);

其中 objects 是一个对象集合,且其中的每个对象的 className 必须一样。

删除 ML.Object 属性值

您可以使用 unset 方法来删除一个实例中的单个属性:

comment.unset('content');
comment.save();

关联数据

对象可能与别的对象有关系。比如对于微博来说,一条微博信息(Post 对象)可能有很 多评论(Comment 对象)。MaxLeap 支持各种关系,包括一对一、一对多和多对多。

一对一关联

一对一关系和一对多关系都可以通过在一个 ML.Object 内保存另一个对象的实例来实现。 比如,每一个 Comment 都对应了一个 Post,创建一个带一条 Comment 的 Post, 你可以这样写:

var post = new Post();
var comment = new Comment();
post.set('content', '这是我的第一条微博信息,请大家多多关照。');
comment.set('content', '期待您更多的微博信息。');
comment.add('post', post);
comment.save()

MaxLeap 内部会自动处理,调用 Comment 的 save 方法就可以同时保存两个新对象。

如果是现有对象想要关联到新对象,你同样可以通过只用它们的 objectId 来连接彼此。 请注意,不能直接像上面的例子那样将现有对象设置进去,而是必须 new 一个新对象并只设置 objectId 属性:

var post = ML.Object.createWithoutData('Post', '5652ae2ba5ff7f00011d1c0b');
var comment = new Comment();
comment.add('post', post);
comment.save();

或者:

var post = new Post();
post.id = '5652ae2ba5ff7f00011d1c0b';
var comment = new Comment();
comment.add('post', post);
comment.save();
一对多关联

把两条评论关联至一条微博中:

var post = new Post();
post.set('content', '这是我的第一条微博信息,请大家多多关照。');

var comment1 = new Comment();
comment1.set('content', '期待您更多的微博信息。');
var comment2 = new Comment();
comment2.set('content', '我也期待。');

post.add('comment', comment1);
post.add('comment', comment2);
post.save()
多对多关联

多对多关系是通过 ML.Relation 来建模的。这样很像在一个 key 中存储一个 ML.Object 数组。但是区别之处在于,在获取附加属性的时候,ML.Relation 不需要同步获取关联的所有 ML.Object 实例。这使得 ML.Relation 比数组的方式可以支持更多实例,读取方式也更加灵活。例如,一个 User 可以喜欢很多 Post。这种情况下,就可以用 relation() 方法保存一个用户喜欢的所有 Post 集合。为了新增一个喜欢的 Post,你可以这样做:

var relation = user.relation('likes');
relation.add(post);
user.save()

仅可以从一个 ML.Relation 中删除一个 post:

relation.remove(post);

默认情况下,relation 关联的对象不回被同步获取到,您可以通过使用 query 方法返回的 ML.Query 对象来获取 ML.Object 的列表,比如:

query.first().then(function(result){
  var relation = result.relation('likes');
  relation.query().find();
});

计数器

计数器是应用常见的功能需求之一。当某一数值类型的字段会被频繁更新,且每次更新操作都是将原有的值增加某一数值,此时,我们可以借助计数器功能,更高效的完成数据操作。并且避免短时间内大量数据修改请求引发冲突和覆盖。

比如记录某用户游戏分数的字段 “score",我们便会频繁地修改,并且当有几个客户端同时请求数据修改时,如果我们每次都在客户端请求获取该数据,并且修改后保存至云端,便很容易造成冲突和覆盖。

递增计数器

此时,我们可以利用increment()方法(默认增量为 1),高效并且更安全地更新计数器类型的字段。如,为了更新记录用户游戏分数的字段 "score",我们可以使用如下方式:

gameScore.increment('score');
gameScore.save();
指定增量
gameScore.increment('score', 3);
gameScore.save();
递减计计数器
gameScore.increment('score', -3);
gameScore.save();

注意: 增量无需为整数,您还可以指定增量为浮点类型的数值。

数组

为了帮你存储数组类数据,MaxLeap 提供了三种操作让你可以原子地改动一个数组的值(当然,他们都需要一个给定的 key):

  • add 在一个数组的末尾加入一个给定的对象
  • addUnique 只会把原本不存在的对象加入数组,所以加入的位置没有保证
  • remove 在一个数组中删除所有指定的实例

比如,我们想在一条微博的属性 "tags” 中加入多个属性值:

post.addUnique('tags', 'Frontend');
post.addUnique('tags', 'JavaScript');
post.save();

数据类型

到现在为止我们使用了 StringNumberML.Object 类型,MaxLeap 同样支持 JavaScript 的 Datenull 类型。 你可以用一个 ML.Object 中嵌套 JavaScript 对象和数组来表述更加结构化的数据:

var number = 123, date = new Date(), array = ['a', 'b'], object = {name: 'test'};
var post = new Post();
post.set('number', number);
post.set('date', date);
post.set('array', array);
post.set('object', object);
post.save();

文件

ML.File的创建和上传

ML.File 可以让您的应用程序将文件存储到服务器中,以应对文件太大或太多,不适宜放入普通 ML.Object 的情况。比如常见的文件类型图像文件、影像文件、音乐文件和任何其他二进制数据(大小不超过 100 MB)都可以使用。 在这个例子中,我们上传一张图片:

  var filePath; // 文件路径
  var name = 'avatar.jpg';
  var ML.File = new ML.File(name, filePath);
  ML.File.save();

注意:

  • 你不需要担心文件名重复的问题。每一次上传都会有一个独一无二的标识符,所以上传多个文件都叫 avatar.jpg 是没有问题的。

获取文件的内容

把上传的文件显示到页面的指定元素中:

<Image source={{uri: file.url()}}/>

删除文件

使用 destroy 方法来删除文件:

file.destroy();

查询

基本查询

使用MLQuery查询 ML.Object 分三步:

  1. 创建一个 ML.Query 对象,并指定对应的 “ML.Object class";
  2. MLQuery 添加过滤条件;
  3. 执行 MLQuery:使用 query.find() 方法查询与条件匹配的 ML.Object 数据。

例如,查询存在 objectId 的 GameScore:

var GameScore = ML.Object.extend('GameScore');
var query = new ML.Query(GameScore);
query = new ML.Query(GameScore);
query.exists('name');
query.equalTo('score', 13);
query.find();

查询条件

equalTo 方法用来过滤符合要求的对象:

query.equalTo('pubUser', 'MaxLeap 官方客服');

notEqualTo 方法用来过滤不符合要求的对象,equalTo 正好相反:

query.equalTo('pubUser', 'MaxLeap 官方客服');

对于类型为数字的属性,您可以对其值的大小进行筛选:

query.greaterThan('score', 7);
query.greaterThanOrEqualTo('score', 7);
query.lessThan('score', 11);
query.lessThanOrEqualTo('score', 11);

您可以使用 select 和一个 keys 的列表来限定返回的字段,比如只获取 “name” 和 “score” 字段(自动包含内建属性, 如 objectId,createdAt 及 updatedAt):

query.select('name', 'score');

剩下的字段可以之后用返回的对象的 fetch 方法来获取:

query.first().then(function(result){
  result.fetch();
});

如果想让返回的对象的某个属性匹配多个值,您可以使用 containedIn,提供一个数组就可以了。比如查询名字为「henry,frank」的 GameScore :

query.containedIn('name',['henry', 'zhou']);

相反地,您可以使用 notContainedIn 方法来查询在集合之外的目标对象。

如果你只想要一个结果,一个更加方便的方法可能是使用 first(),而不是 find() 方法:

query.first()

使用 skip 跳过前面的结果,这可能对分业很有用:

query.skip(10); // 跳过前 10 条结果

你可以用设定 limit 的方法来限定返回的结果数,默认的返回结果数是 100,但是任 何 1 到 1000 之间的数值都是合法的,在 0 到 1000 范围之外的都强制转成默认的 100。

query.limit(10); // 最多返回 10 条结果

对于可以排序的类型,比如 numberstring,你可以控制返回结果的顺序:

query.ascending('pubUser'); // 升序

query.descending('pubTimestamp'); // 降序

对数组值做查询

对于属性值是数组的情况,您可以这样查询数组的值中有 “henry” 的游戏记录:

query.equalTo('developer', 'henry');

您同样可以用下面的方式找到属性值中同时包含 “henry”,“frank” 的游戏记录:

query.containsAll('developer', ['henry', 'frank']);

此外,您还可以根据数组长度来查询,比如查询 developer 人数为 2 的游戏记录:

query.sizeEqualTo('developer', 2);

对字符串类型做查询

使用 startsWith() 来限制属性值以一个特定的字符串开头,比如找出 name 以 “bai” 开头的游戏记录:

query.startsWith('name', 'bai');

关系查询

对于查询关系型数据来说有几种不同的方式,如果您想要获取的对象中有某个属性包含一个特定的 ML.Object,您可以使用 equalTo(),就像对于别的数据类型一样。

例如,如果每条 Comment 的 post 字段都有一个 Post 对象,那么找出指定 post 下的 comment:

// 假设 myPost 是已经创建的对象。
var query = new ML.Query(Comment);
query.equalTo('post', myPost);
query.find();

如果想得到其字段中包含的子对象满足另一个查询的结果,你可以使用 matchesQuery() 操作。 注意默认的结果条数限制 100 和最大值 1000 也同样适用于子查询,所以对于大的数据集您可能需要小心构建查询条件,否则可能出现意料之外的状 况。例如,为了找到有图片的 post 的 comment,您可以:

var innerQuery = new AV.Query(Post);
innerQuery.exists('image');
var query = new AV.Query(Comment);
query.matchesQuery('post', innerQuery);
query.find().then(function(comments) {
    // comments 包含有所有带图片 post 的 comment.
  });

如果您想要获取某字段中包含的子对象不满足指定查询的结果,你可以使用 doesNotMatchQuery()。例如,为了找到针对不含图片的 post 的 comment,可以这样:

var innerQuery = new AV.Query(Post);
innerQuery.exists('image');
var query = new AV.Query(Comment);
query.doesNotMatchQuery('post', innerQuery);
query.find().then(function(comments) {
    // comments 包含所有不带图片 post 的 comment.
  })

地理位置

MaxLeap 提供 ML.GeoPoint 对象,帮助用户根据地球的经度和纬度坐标进行基于地理位置的信息查询。

创建 ML.GeoPoint

ML.GeoPoint 需要提供两个参数:第一个为纬度(正为北纬),第二个参数为经度(正为东经)。

var geoPoint = new ML.GeoPoint(40, -30);

ML.GeoPoint 对象可被存储在 ML.Object 中:

var post = new Post();
post.set('location', geoPoint);

地理位置查询

您可以通过 query.near() 方法添加一个附近位置查询条件, 然后通过 query.find() 方法获取结果:

var postGeoPoint = post.get('location');
var query = new ML.Query(Post);
query.near('location', postGeoPoint);
query.limit(10);
query.find();

这时会返回一个距离 postGeoPoint 的排序列表。注意如果在 ML.Query 上调用了 ascending()/descending() 的话,指定的排序属性会取代距离。

为了按距离限制返回的结果,你还可以使用 withinMiles()withinKilometers()withinRadians()

同样地,也可以查询在特定地域的对象。为了找到用矩形表示的一块地域中的对象,需要在 ML.Query 中加入 withinGeoBox() 约束条件:

var query = new ML.Query(Post);
var southwest = new ML.GeoPoint(39.97, 116.33);
var northeast = new ML.GeoPoint(39.99, 116.37);
query.withinGeoBox('location', southwest, northeast);
query.limit(10);
query.find();

数据安全

每个到达 MaxLeap 云服务的请求是由移动端 SDK,管理后台,云代码或其他客户端发出,每个请求都附带一个 security token。MaxLeap 后台可以根据请求的 security token 确定请求发送者的身份和授权,并在处理数据请求的时候,根据发送者的授权过滤掉没有权限的数据。

具体的介绍及操作方法,请参考 数据存储-使用指南

云代码

简介

什么是云代码服务

云代码是部署运行在 MaxLeap 云引擎上的代码,您可以用它来实现较复杂的,需要运行在云端的业务逻辑。它类似于传统的运行在 Web server上的 Web Service或 RESTful API。它对外提供的接口也是 RESTful API,也正是以这种方式被移动应用调用。

目前支持 Java,其他语言尽请期待。

准备

如果您尚未安装 SDK,请先查阅快速入门指南,安装 SDK 并使之在 Xcode 中运行。

注意:我们支持 iOS 7.0 及以上版本。

首先,需要开发云代码,实现所需的接口和 HOOK,开发以及发布过程请根据您的需求选择对应服务端语言

Java 开发指南

云代码调用

发布云代码之后,客户端可以使用 ML.Cloud.run(name, data, options) 方法调用云函数。

假如在 CloudCode 中定义了一个名称为 hello 的函数,带一个名字为 name 的参数,返回值为输入的参数字典。现在调用这个云函数:

import ML from 'maxleap-react-native'

ML.Cloud.run('hello', {name: 'Alex'})
.then(result => {
    console.log('cloud function result is ' + result)
})

账号服务

用户

ML.User 是一个 ML.Object 的子类,它继承了 ML.Object 所有的方法,具有 ML.Object 相同的功能。不同的是,ML.User 增加了一些特定的关于用户账户相关的功能。

字段说明

ML.User 除了从 ML.Object 继承的属性外,还有几个特定的属性:

属性名类型介绍是否必需或唯一
usernameString用户的用户名必需
passwordString用户的密码必需
emailString用户的电子邮件地址可选
emailVerifiedBoolean电子邮件是否验证可选
masterKeyString用户注册应用的MasterKey可选
installationIdsString用户完成的所有安装的InstallationId可选

注意:

  • 请确保用户名和电子邮件地址是独一无二的。
  • 系统会自动收集 masterKeyinstallationIds 的值。

注册用户

  1. 创建 ML.User 对象,并提供必需的 username 和 password
  2. 调用 user.signUp() 方法保存至云端。
var r = new Date().getTime();
var user = new ML.User();
user.set('username', 'my name' + r);
user.set('password', 'my pass');
user.signUp()

注意:

  • 在注册过程中,服务器会进行注册用户信息的检查,以确保注册的用户名和电子邮件地址是独一无二的。此外,服务端还会对用户密码进行不可逆的加密处理,不会明文保存任何密码,应用切勿再次在客户端加密密码,这会导致重置密码等功能不可用。
  • 注册使用的是 signUp() 方法,而不是 save() 方法。
  • 如果注册不成功,您可以查看返回的错误对象。最有可能的情况是,用户名或电子邮件已经被另一个用户注册。这种情况您可以提示用户,要求他们尝试使用不同的用户名进行注册。
  • 您也可以要求用户使用 Email 做为用户名注册,这样做的好处是,您在提交信息的时候可以将输入的“用户名“默认设置为用户的 Email 地址,以后在用户忘记密码的情况下可以使用 MaxLeap 提供的重置密码功能。

登录

您可以通过 ML.User.logIn() 方法登录:

ML.User.logIn('yourname', 'yourpass');

邮箱验证

MaxLeap 提供强大的邮箱验证服务,您只需在 Console >> 应用设置 >> 电子邮件设置 中 开启 “验证用户的邮箱”, 系统便会自动在 ML.User 中添加 emailVerified 字段。并且,当 ML.User 的 email 字段被赋值或者修改, 且 emailVerified 字 字段的值为 false. MaxLeap 便会自动向用户发送一个链接,用户点击链接后便会将 emailVerified 设置为true.

emailVerified字段有三种状态:

  • true - 用户通过点击系统发送的链接验证邮箱成功
  • false - 用户还未验证邮箱,或者验证失败
  • 空 - 邮箱验证功能未开,或者用户未提供邮箱

当前用户

如果用户在每次打开您的应用程序时都要登录,这将会直接影响到您应用的用户体验。为了避免这种情况,您可以使用缓存的 currentUser 对象。

每当您注册成功或是第一次登录成功,都会在本地磁盘中有一个缓存的用户对象,您可以这样来获取这个缓存的用户对象来进行登录:

ML.User.currentAsync().then(currentUser => {
    // ...
});

当然,您也可以使用如下方法清除缓存用户对象:

ML.User.logOut();

重置密码

如果用户忘记密码,MaxLeap提供了一种方法,让用户安全地重置起密码。 重置密码的流程很简单,开发者只要求用户输入注册的电子邮件地址即可:

ML.User.requestPasswordReset('youremail@xx.xx');

如果邮箱与用户注册时提供的邮箱匹配,系统将发出密码重置邮件。密码重置流程如下:

  • 用户输入他们的电子邮件,请求重置自己的密码。
  • MaxLeap 向用户提供的邮箱发送一封电子邮件,该邮件提供密码重置链接。
  • 用户根据向导点击重置密码链接,打开一个ML的页面,输入一个新的密码。
  • MaxLeap 将用户的密码重置为新输入的密码。

匿名用户

匿名用户是指提供用户名和密码,系统为您创建的一类特殊用户,它享有其他用户具备的相同功能。不过,一旦注销,匿名用户的所有数据都将无法访问。如果您的应用需要使用一个相对弱化的用户系统时,您可以考虑 MaxLeap 提供的匿名用户系统来实现您的功能。

您可以通过 anonymousSignUp() 注册一个匿名的用户账号:

var user = new ML.User();
user.anonymousSignUp();

注意:SDK 会自动创建匿名用户

因为一些特殊原因,SDK 中有一个逻辑:它会在没有用户登录的情况下自动创建一个匿名用户,有关匿名用户,请查看匿名用户介绍。

- 启动应用程序时,若 currentUser 为空,则会创建一个匿名用户 - 用户登出后,SDK 会自动创建一个匿名用户 - 这个过程是定时器驱动的,有一定的延迟,如果应用在某个时刻需要匿名登录,却发现当前用户为空,就需要手动创建匿名用户

注意:还需要特别注意的是,假如当前用户是一个匿名用户,这个时候直接调用注册接口,sdk 会把这个匿名用户更新成为一个普通用户,而不会创建一个新用户。

在 Console 中管理用户

User 表是一个特殊的表,专门存储 ML.User 对象。在Console >> 开发中心 >> 云数据库,您会看到一个 _User 表。

FAQ

即时通讯

Author: Marvin
Github: https://github.com/zhoucen

简介

使用 MaxLeap 的即时通讯服务,可以轻松实现一个实时聊天应用,或者一个联机对战类的游戏。除聊天室外的聊天记录都保存在云端,离线消息会通过消息推送及时送达,推送的消息文本可以灵活定制。

MaxIMLib

MaxIMLib 是不含界面的基础 IM 通讯能力库,封装了通信能力和会话、消息等对象。引用到 App 工程中后,需要开发者自己实现 UI 界面,相对较轻量,适用于对 UI 有较高订制需求的开发者。

本 SDK 实现轻量、高效、无依赖,其中浏览器支持涵盖了移动终端的浏览器及各种 WebView,包括微信、PhoneGap、Cordova 的 WebView。

Demo

安装与配置

浏览器环境

下载SDK

下载好之后,在页面中加载 dist/ML.im.js 后即可使用 ML.im 全局变量。

示例代码

// 最简的示例代码,请换成自己的 appId,可以通过浏览器多个标签模拟多用户通信
var appId = '{{appid}}';
// clientId 就是你自己的app 的 Client Key 或者 Javascript Key 或者 REST API Key 或者 Master Key
var clientId = 'Y3FxbHE2aTJmQ2dQazYtQVlvc0NnQQ';
// userId 就是你自己的app里面的用户id
var userId = 'user1';
// installId 是你的设备id
var installId = 'M3pyVEdsSFBBZm5UTDlLMTB3a0xYdw'
var im;

// 创建实时通信实例(支持单页多实例)
im = ML.im({
         appId: appId,
         clientId: clientId,
         userId: userId,
         installId: installId,
         region: 'cn'
       },function(){
                 console.log('login success!');
                 });
// 当前 SDK 版本
console.log('当前 SDK 版本是 ' + ML.im.version);

// 像好友发送消息
im.toFriend('user2').text('hello! user2!').ok();

// 在Group里面发送消息
im.toGroup('group1').text('hello! I'm user1!').ok();

// 在Group里面发送消息
im.toRoom('room1').text('hello! I'm user1!').ok();

与 iOS、Android 等客户端通信

JavaScript 实时通信 SDK 可以与其他客户端通信。当你不仅仅只是基于 Web 来实现一个实时通信程序,可以通过使用 Maxleap 提供的其他类型(iOS、Android等)的 SDK 实现多端互通。

我们的SDK支持发送多种消息格式,分别为:

  • text(文本)
  • image(图片)
  • audio(声音)
  • video (视频)

示例

// 与 iOS、Android 等 SDK 通信

// 发送文本
im.toFriend('user2').text('hello! user2!').ok();

// 发送图片
// data 是个FormData类型的对象或者是字符流
var data = ...
im.toFriend('user2').image(data).ok();

// 发送声音
// data 是个FormData类型的对象或者是字符流
var data = ...
im.toFriend('user2').audio(data).ok();

// 发送视频
// data 是个FormData类型的对象或者是字符流
var data = ...
im.toFriend('user2').video(data).ok();

方法列表

全局命名空间

Maxleap JavaScript 相关 SDK 都会使用「ML」作为命名空间。

ML.im

这是创建实时通信对象的方法,会启动实时通信的连接。自动调用 connect 方法,内部与服务器匹配,并建立 WebSocket 连接。内部会自动维持与服务器的链接稳定。

另外,此方法支持多实例,也就是说,你可以在一个页面中,创建多个实例来实现聊天。

ML.im(options, callback)

输入

目前可以采取两种不同的模式登录

使用用户已有账号系统

模式一:使用自己的账号系统,那么只需要提供 userId

使用 MaxLeap 账号系统

模式二:通过用户名及密码,则需要 username 和 password

模式三:使用手机号码登录,那么需要 phone 和 password

模式四:使用第三方登录,那么需要 oauth 信息

参数类型约束默认说明
optionsObject必须配置实时通信服务所需的必要参数。其中包括:
     appIdString必须应用的 appId,
     clientIdString必须app 的 Client Key 或者 Javascript Key 或者 REST API Key 或者 Master Key
     userIdString模式一必须当前客户的唯一 id,用来标示当前客户。
     usernameString模式二必须当前客户的username。
     passwordString模式二或者模式三必须当前客户的password。
     phoneString模式三必须当前客户的phone。
     oauthObject模式四必须第三方登录的oauth信息。
     installIdString当前客户端的设备 id,用来标示当前设备。如果需要离线接收推送消息的话,必须提供。

返回

Object 返回 imObject(实时通信对象),其中有后续调用的方法,支持链式调用。

示例

// 最简的示例代码,请换成自己的 appId,可以通过浏览器多个标签模拟多用户通信
var appId = '{{appid}}';
// clientId 就是你自己的app 的 Client Key 或者 Javascript Key 或者 REST API Key 或者 Master Key
var clientId = 'Y3FxbHE2aTJmQ2dQazYtQVlvc0NnQQ';
// (模式一)userId 就是你自己的app里面的用户id
var userId = 'user1';
// (模式二)username
var username = 'username';
// (模式二 或者 模式三)password
var password = 'password';
// (模式三)phone
var phone = '13810001000';
// (模式四)oauth信息
var oauth = {};
// installId 是你的设备id
var installId = 'M3pyVEdsSFBBZm5UTDlLMTB3a0xYdw'
var im;

// 创建实时通信实例--模式一(支持单页多实例)
im = ML.im({
         appId: appId,
         clientId: clientId,
         userId: userId,
         installId: installId
       },function(data){
         /* 处理登录结果,当登录失败时服务器最后会断开连接。消息结构如下:
             {
                 id: 'YOUR_LOGIN_USER_ID',    // 模式一为userId。模式二为Maxleap账号系统中的用户的objectId
                 success: true,        //  是否登录成功
                 error: 5003        // 错误码,仅当登录失败时
             }
        */
                 });
// 创建实时通信实例--模式二(支持单页多实例)
im = ML.im({
         appId: appId,
         clientId: clientId,
         username: username,
         password: password,
         installId: installId
       },function(data){
         /* 处理登录结果,当登录失败时服务器最后会断开连接。消息结构如下:
         {
             id: 'YOUR_LOGIN_USER_ID',    // 模式一为userId。模式二为Maxleap账号系统中的用户的objectId
             success: true,        //  是否登录成功
             error: 5003        // 错误码,仅当登录失败时
         }
         */
         });
// 创建实时通信实例--模式三(支持单页多实例)
im = ML.im({
         appId: appId,
         clientId: clientId,
         phone: phone,
         password: password,
         installId: installId
       },function(data){
         /* 处理登录结果,当登录失败时服务器最后会断开连接。消息结构如下:
         {
             id: 'YOUR_LOGIN_USER_ID',    // 模式一为userId。模式二为Maxleap账号系统中的用户的objectId
             success: true,        //  是否登录成功
             error: 5003        // 错误码,仅当登录失败时
         }
         */
         });

// 创建实时通信实例--模式四(支持单页多实例)
im = ML.im({
        appId: appId,
        clientId: clientId,
        oauth: oauth,
        installId: installId
      },function(data){
        /* 处理登录结果,当登录失败时服务器最后会断开连接。消息结构如下:
        {
            id: 'YOUR_LOGIN_USER_ID',    // 模式一为userId。模式二为Maxleap账号系统中的用户的objectId
            success: true,        //  是否登录成功
            error: 5003        // 错误码,仅当登录失败时
        }
        */
        });

ML.im.version

获取当前 SDK 的版本信息。

AV.realtime.version

返回

String 返回当前版本。

示例

// 返回版本号
console.log('当前版本是:' + AV.realtime.version);

ML.im.userInfo

获取指定user的信息

ML.im.userInfo(userid, function(err, data){
    })

参数

参数类型约束默认说明
useridString必须用户id

callback 返回

Object 返回指定user的信息。

示例返回值

{
 {
     "sessions": 1,
     "installs": ['install1','install2'],
     "friends": [
         "bar"
     ],
     "attributes": {
         "name": "猴哥",
         "description": "我是猴哥我怕誰",
         "power": "3000000"
     },
     "rooms": [
         "da6469c86847458fb4fe82a04cf60424",
         "2a416cb1847d4700b0431f193f6418b7"
     ],
     "groups": [
         "cafe9923f8ce4edaabb6cae9b8333ec6",
         "46b9c7cc4fc6428185a2e3a1c1f9e26e",
         "6cd90bf2c8fc4973af25af02ce13b75b"
     ]
 }
}

ML.im.listFriends

获取指定user的好友列表

ML.im.listFriends(userid, function(err, data){
    }, withDetail)

参数

参数类型约束默认说明
useridString必须用户id
withDetailBoolean可选是否需要返回详细信息

callback 返回

Array 返回指定user的好友列表。

示例返回值

// 如果withDetail 为false,返回好友id列表
["friend1","friend2","friend3"]
// 如果withDetail 为true,返回好友列表
[{"id": "friend1","online": false},{"id": "friend2","online": false},{"id": "friend3","online": true}]

ML.im.addFriend

将user1和user2加为好友

ML.im.addFriend(userid, friendid, function(err, data){
    })

参数

参数类型约束默认说明
useridString必须用户id
friendidString必须用户id

callback 返回


#### 示例返回值

```javascript
{
  "id": "b9d61d4e80ad1f6d",    // 建立友谊的唯一标识ID
  "from": "foo",    // 谁发起的加好友
  "to": "bar",    // 谁被加的好友
  "ns": "56a86320e9db7300015438f7",   // 命名空间,等价于应用ID
  "ts": 1454655122174   // 创建时间
}

ML.im.rmFriend

将user1和user2解除好友关系

ML.im.rmFriend(userid, friendid, function(err, data){
    })

参数

参数类型约束默认说明
useridString必须用户id
friendidString必须用户id

callback 返回

String 空字符串

示例返回值

ML.im.getRecentChat

获取user1和user2的聊天记录在指定时间前的指定条数。

ML.im.getRecentChat(userid, friendid, ts, size, function(err, data){
    })

参数

参数类型约束默认说明
useridString必须用户id
friendidString必须用户id
tsString必须时间戳
sizeString必须聊天记录数

callback 返回

Array 聊天记录列表

示例返回值

[
  {
    "speaker": "speaker id",    // 发言者
    "content": {    // 消息内容
      "media": 0,    // 媒体类型: 0=纯文本,1=图片,2=音频,3=视频
      "body": "you are sb"    // 媒体body
    },
    "ts": 1454490959094    // 时间戳
  }
]

ML.im.listGroups

获取user的Group列表。

ML.im.listGroups(userid, function(err, data){
    }, withDetail)

参数

参数类型约束默认说明
useridString必须用户id
withDetailBoolean可选是否需要返回详细信息

callback 返回

Array Group列表

示例返回值

// 如果withDetail 为false,返回Group id列表
["7c9fb6ca88ed41d58f69bb40b779d5bc"]
// 如果withDetail 为true,返回Group详细信息列表
[
  {
    "id": "7c9fb6ca88ed41d58f69bb40b779d5bc",    // 群组ID
    "name": "dog fucker",    // 群组名称
    "owner": "foo",    // 群组管理员
    "members": ["member1","member2","member3","foo"],    // 群组成员
    "ts": 1456306512958
  }
]

ML.im.addGroup

创建一个新的Group。

ML.im.addGroup(data, function(err, data){
    })

参数

参数类型约束默认说明
dataObject必须创建一个Group必须的信息

{ “owner”: “user1”, // 创建人 “name”: “groupName”, // 群组名称 “members”: [“member1”,“member2”] // 成员 }

callback 返回

String Group ID

示例返回值

7c9fb6ca88ed41d58f69bb40b779d5bc

ML.im.getGroup

获取一个Group的信息。

ML.im.getGroup(groupid, function(err, data){
    })

参数

参数类型约束默认说明
groupidString必须Group ID

callback 返回

Object Group 信息

示例返回值

{
  "owner": "jerry", // 群组管理员
  "ts": 1461607141000,
  "members": [
    "jerry"// 群组成员ID
  ],
  "attributes": {
    "name": "美女起来high",
    "description": "聊天交友群"
  }
}

ML.im.updateGroup

修改一个Group的信息。

ML.im.updateGroup(groupid, data, function(err, data){
    })

参数

参数类型约束默认说明
groupidString必须Group ID
dataObject必须需要修改的信息

{ “name”: “new group name”, // 可选项 “owner”: “new owner”, // 可选项 “members”: [“new member1”] // 可选项, 完全覆盖旧成员表 }

callback 返回

String 空字符串

示例返回值

ML.im.rmGroup

删除一个Group。

ML.im.rmGroup(groupid, function(err, data){
    })

参数

参数类型约束默认说明
groupidString必须Group ID

callback 返回

String 空字符串

示例返回值

ML.im.addGroupMembers

把user添加到group中。

ML.im.addGroupMembers(groupid, data, function(err, data){
    })

参数

参数类型约束默认说明
groupidString必须Group ID
dataObject必须需要添加的成员

{ “members”:[“member1”,“member2”] }

callback 返回

String 空字符串

示例返回值

ML.im.rmGroupMembers

把user从group中移除。

ML.im.rmGroupMembers(groupid, data, function(err, data){
    })

参数

参数类型约束默认说明
groupidString必须Group ID
dataObject必须需要移除的成员

{ “members”:[“member1”,“member2”] }

callback 返回

String 空字符串

示例返回值

ML.im.getGroupChat

获取group的聊天记录在指定时间前的指定条数。

ML.im.getGroupChat(groupid, ts, size, function(err, data){
    })

参数

参数类型约束默认说明
groupidString必须Group id
tsString必须时间戳
sizeString必须聊天记录数

callback 返回

Array 聊天记录列表

示例返回值

[
  {
    "speaker": "speaker id",    // 发言者
    "content": {    // 消息内容
      "media": 0,    // 媒体类型: 0=纯文本,1=图片,2=音频,3=视频
      "body": "you are sb"    // 媒体body
    },
    "ts": 1454490959094    // 时间戳
  }
]

ML.im.addRoom

创建一个新的Room。

ML.im.addRoom(data, function(err, data){
    })

参数

参数类型约束默认说明
dataObject必须创建一个Room必须的信息

{ “name”: “av room”, // 聊天室名称 “members”: [“user1”,“user2”]] // 聊天室成员, 可选项 }

callback 返回

String Room ID

示例返回值

  "7c9fb6ca88ed41d58f69bb40b779d5bc" // 聊天室ID

ML.im.getRoom

获取一个Room的信息。

ML.im.getRoom(roomid, function(err, data){
    })

参数

参数类型约束默认说明
roomidString必须Room ID

callback 返回

Object Room 信息

示例返回值

{
  "ts": 1461608237000,
  "members": [
    "foo",
    "bar"
  ],
  "attributes": {
    "name": "test room1"
  }
}

ML.im.updateRoom

修改一个Room的信息。

ML.im.updateRoom(roomid, data, function(err, data){
    })

参数

参数类型约束默认说明
roomidString必须Room ID
dataObject必须需要修改的信息

{ “name”: “test_group333”, “members”: [“baz”] }

callback 返回

String 空字符串

示例返回值

ML.im.rmRoom

删除一个Room。

ML.im.rmRoom(roomid, function(err, data){
    })

参数

参数类型约束默认说明
roomidString必须Group ID

callback 返回

String 空字符串

示例返回值

ML.im.addRoomMembers

把user添加到room中。

ML.im.addRoomMembers(roomid, data, function(err, data){
    })

参数

参数类型约束默认说明
roomidString必须Group ID
dataObject必须需要添加的成员

{ “members”:[“member1”,“member2”] }

callback 返回

String 空字符串

示例返回值

ML.im.rmRoomMembers

把user从room中移除。

ML.im.rmRoomMembers(roomid, data, function(err, data){
    })

参数

参数类型约束默认说明
roomidString必须Group ID
dataObject必须需要移除的成员

{ “members”:[“member1”,“member2”] }

callback 返回

String 空字符串

示例返回值

ML.im.sysToAll

给所有用户发消息

ML.im.sysToAll(data, function(err, data){
    })

参数

参数类型约束默认说明
dataObject必须需要发的消息

{ “content”: { “media”: 0, “body”: “YOUR_MESSAGE_BODY” }, “ts”: 1455620323804 }

callback 返回

String 空字符串

示例返回值

ML.im.sysToUser

给指定user发消息

ML.im.sysToUser(userid, data, function(err, data){
    })

参数

参数类型约束默认说明
useridString必须用户 id
dataObject必须需要发的消息

{ “content”: { “media”: 0, “body”: “YOUR_MESSAGE_BODY” }, “ts”: 1455620323804 }

callback 返回

String 空字符串

示例返回值

ML.im.sysToGroup

给指定group发消息

ML.im.sysToGroup(groupid, data, function(err, data){
    })

参数

参数类型约束默认说明
groupidString必须Group id
dataObject必须需要发的消息

{ “content”: { “media”: 0, “body”: “YOUR_MESSAGE_BODY” }, “ts”: 1455620323804 }

callback 返回

String 空字符串

示例返回值

ML.im.sysToRoom

给指定room发消息

ML.im.sysToRoom(roomid, data, function(err, data){
    })

参数

参数类型约束默认说明
roomidString必须Room id
dataObject必须需要发的消息

{ “content”: { “media”: 0, “body”: “YOUR_MESSAGE_BODY” }, “ts”: 1455620323804 }

callback 返回

String 空字符串

示例返回值

ML.im.attachment

上传文件(如果是图片类型,系统将会自动生成缩略图)

ML.im.attachment(data, function(err, data){
    })

参数

参数类型约束默认说明
dataFormData必须文件对象

callback 返回

String 空字符串

示例返回值

[
  "http://im.maxleap.cn/b9d61d4e/3dee7932.jpg",    // 原图地址
  "http://im.maxleap.cn/b9d61d4e/3dee7932.sm.jpg"    // 缩略图地址
]

ML.im.onMessage

注册onMessage回调

ML.im.onMessage(function(msg){
    })

msg

Obejct 消息

消息示例

{
    from: {
        id: 'FROM_ID',
        type: 0,    // 0=friend,1=group,2=room
        gid: 'GROUP_OR_ROOM_ID'    //require if type is 1 or 2
    },
    content: {
        media: 0,
        body: 'YOUR_MESSAGE_BODY'
    },
    ts: 1455613127766 // send timestamp
}

ML.im.online

注册好友上线事件的回调

ML.im.online(function(msg){
    })

msg

Obejct 消息

消息示例

"<onlineUserID>"

ML.im.offline

注册好友下线事件的回调

ML.im.offline(function(msg){
    })

msg

Obejct 消息

消息示例

 "<offlineUserID>"

ML.im.sys

注册系统消息的回调

ML.im.sys(function(msg){
    })

msg

Obejct 消息

消息示例

{
    content: {
        media: 0,
        body: 'SYSTEM_MESSAGE_BODY'
    },
    ts: 1455620323804
}

ML.im.yourself

当相同账号在不同终端登录后,别的终端发送的消息,当前终端也可以收到。注册此事件的回调。

ML.im.yourself(function(msg){
    })

msg

Obejct 消息

消息示例

{
        to: {
            id: 'RECEIVER_ID',
            type: 0
        },
        content: {
            media: 0,
            body: 'MESSAGE_BODY'
        },
        ts: 1455620323804
    }

ML.im.searchUsers

搜索用户

  ML.im.searchUsers(size,skip,name,data, function (error,value) {

  });

参数

参数类型约束默认说明
sizeint可选显示的条数
skipint可选跳过的条数
namestring可选排序的字段(多个字段直接用“,"隔开)
dataobject可选自定义的属性字段如{‘name’:'小不点’}

callback 返回

object callback返回

返回示例值

[{
    "id":"foo",
    "ts":1461570739830,
    "attributes":{
        "name":"小不点"
    },
    "online":false
},
... ...

]

ML.im.setUserAttributes

设置用户自定义属性

    ML.im.setUserAttributes(user,data, function (error,value) {

    });

参数

参数类型约束默认说明
userstring必须用户的id
dataobject必须需要设置的属性(如:{'name’:'混世魔王’,'age’:99999})

callback返回


### ML.im.coverSetUserAttributes

覆盖设置用户自定义属性

```javascript
  ML.im.coverSetUserAttributes(user,data, function (error,data) {

  });

参数

参数类型约束默认说明
userstring必须用户的id
dataobject必须需要设置的属性(如:{'name’:'西门吹雪’})

callback返回


### ML.im.getUserAttributes

获取用户自定义属性

```javascript
    ML.im.getUserAttributes(user, function (error,data) {

    });

参数

参数类型约束默认说明
userstring必须用户id

callback返回


#### 返回值示例

```javascript
{
    "bar": "baz",
    "gender": "male",
    "foo": "bar",
    "name": "隔壁老王",
    "baz": "qux",
    "age": 46
}

ML.im.getUserOneAttribute

获取用户自定义属性

    ML.im.getUserOneAttribute(user,data, function (error,data) {

    });

参数

参数类型约束默认说明
userstring必须用户id
datastring必须自定义的属性名称

callback返回



### ML.im.rmUserAttributes

删除用户自定义属性

```javascript
 ML.im.rmUserAttributes(user, function (error,data) {

 });

参数

参数类型约束默认说明
userstring必须用户id

callback返回



### ML.im.addOrModifyPassenger

新增或修改游客信息

```javascript
  ML.im.addOrModifyPassenger(passenger, function (error,data) {

  });

参数

参数类型约束默认说明
passengerobject必须游客信息(如:{ 'id’:'jessicaZhe’,&'desc’:'我是游客,我怕谁’ }// 可选项, 如果设置则强制使用该ID, 否则系统会随机分配一个ID)

callback返回



### ML.im.getPassenger

获取游客信息

```javascript
    ML.im.getPassenger(passengerId, function (error,data) {

    });

参数

参数类型约束默认说明
passengerIdstring必须游客id

callback返回

#### 返回值示例

```javascript
    {
        "des": "我是一个游客",
        "tel": 1302013,
        "xxx": "hello"
    }

ML.im.getPassengerRecentChat

获取游客的聊天记录

    ML.im.getPassengerRecentChat(passenger,user,ts,size,function (error,data) {

    });

参数

参数类型约束默认说明
passengerstring必须游客id
userstring必须用户id
tsstring必须时间戳
sizeint必须显示的条数

callback返回

#### 返回值示例

```javascript
[
    {
        "ts": 1461635974546,
        "speaker": "jerryJone",
        "content": {
            "media": 0,
            "body": "hi"
        }
    },
    {
        "ts": 1461636003006,
        "speaker": "jerry",
        "content": {
            "media": 0,
            "body": "你好!"
        }
    },
    {
        "ts": 1461636016786,
        "speaker": "jerryJone",
        "content": {
            "media": 0,
            "body": "嘿嘿"
        }
    }
]

ML.im.searchGroups

搜索群组

    im.searchGroups(size,skip,sort,data, function (error,value) {

    });

参数

参数类型约束默认说明
sizeint可选显示的条数
skipint可选跳过多少条
sortstring可选排序字段
dataobject可选自定义的属性(如:{'description’:'搞基’})

callback返回

array callback返回一个数组

返回示例


    {
        "id": "86f42c3d79f94c1fa65dbb5a54adfabb",
        "owner": "foo",
        "ts": 1460070742000,
        "attributes": {
            "name": "mygroup"
        }
    },
    {
        "id": "4889ccb75c07432e8d6fa653658ea693",
        "owner": "foo",
        "ts": 1461032499000,
        "attributes": {
            "name": "sbsbsbsb"
        }
    },
    ... ...
]

ML.im.setGroupAttributes

设置群组自定义属性

    ML.im.setGroupAttributes(group,data,function (error,value) {

    });

参数

参数类型约束默认说明
groupstring必须群组id
dataobject必须需要设置的属性(如:{name:'专业交流群’,'description’:'专业交流一百年’})

callback返回

object callback返回空对象

ML.im.coverSetGroupAttributes

覆盖设置群组自定义属性

    ML.im.coverSetGroupAttributes(group,data, function (error,value) {

    });

参数

参数类型约束默认说明
groupstring必须群组id
dataobject必须需要设置的属性(如:{name:'专业交流群’,'description’:'专业交流一百年’})

callback返回

object callback返回空对象

ML.im.getGroupAttributes

获取群组自定义属性

     im.getGroupAttributes(group, function (error,data) {

    });

参数

参数类型约束默认说明
groupstring必须群组id

callback


#### 返回示例

```javascript
{
    "name": "摄影爱好者群",
    "description": "爱摄影就来吧"
}

ML.im.getGroupOneAttribute

获取群组的某个自定义属性

    ML.im.getGroupOneAttribute(group,attr, function (error,data) {

    });

参数

参数类型约束默认说明
groupstring必须群组id
attrstring必须自定义属性的字段(如:description)

callback返回


### ML.im.rmGroupAttributes

删除群组自定义属性

```javascript
    im.rmGroupAttributes(group, function (error,data) {

    });

参数

参数类型约束默认说明
groupstring必须群组id

callback返回


### ML.im.searchRooms

搜索聊天室

```javascript
    ML.im.searchRooms(size,skip,name,data, function (error,value) {

    });

参数

参数类型约束默认说明
sizeint可选显示的条数
skipint可选跳过多少条
sortstring可选排序字段
dataobject可选自定义的属性(如:{'description’:'搞基’})

callback返回

array callback返回一个数组

返回示例

    [
        {
            "id": "c0eebb302b1345fd983345336dd4eaa6",
            "attributes": {
                "name": "千年恋",
                "description": "千年等候!"
            }
        },
        {
            "id": "4217fd2d424d47d78907c509b8bc8403",
            "attributes": {
                "name": "天涯阁",
                "description": "天涯共此时!"
            }
        },
        ... ...
    ]

ML.im.setRoomAttributes

设置聊天室自定义属性

    ML.im.setRoomAttributes(room,data,function (error,value) {

    });

参数

参数类型约束默认说明
roomstring必须聊天室id
dataobject必须需要设置的属性(如:{name:'大家来聊天’,'description’:'开心交流’})

callback返回

object callback返回空对象

ML.im.coverSetRoomAttributes

覆盖设置聊天室自定义属性

    ML.im.coverSetRoomAttributes(room,data}, function (error,value) {

    });

参数

参数类型约束默认说明
roomstring必须聊天室id
dataobject必须需要设置的属性(如:{name:'大家来聊天二’,'description’:'开心交流二’})

callback返回

object callback返回空对象

ML.im.getRoomAttributes

获取聊天室自定义属性

    ML.im.getRoomAttributes(room, function (error,data) {

    });

参数

参数类型约束默认说明
roomstring必须聊天室id

callback


#### 返回示例

```javascript
{
    "name": "大家来聊天二",
    "description": "开心交流二"
}

ML.im.getRoomOneAttribute

获取聊天室的某个自定义属性

    ML.im.getRoomOneAttribute(room,attr, function (error,data) {

    });

参数

参数类型约束默认说明
roomstring必须群组id
attrstring必须自定义属性的字段(如:description)

callback返回



### ML.im.rmRoomAttributes

删除聊天室自定义属性

```javascript
    ML.im.rmRoomAttributes(room, function (error,data) {

    });

参数

参数类型约束默认说明
roomstring必须聊天室id

callback



## 错误码

错误码|含义
---|---
5001|非法的参数错误
5002|数据库错误
5003|权限错误
5004|请求的对象不存在
5005|请求参数存在冲突
5006|S3上传错误
5007|图片处理错误

## FAQ
敬请期待

移动支付 npm version

简介

目前支持支付宝、微信、银联支付等渠道,支持支付及查询交易记录功能。我们将持续更新,支持更多支付平台和更多功能,敬请期待。

使用

填写各支付渠道信息

在集成 MaxPay iOS SDK 之前,请确保正确填写了将要集成的支付渠道的支付参数。

  1. 创建 MaxLeap 应用
  2. 打开支付渠道配置页面(MaxLeap 控制台 -> 我的应用 -> 应用设置 -> 支付设置 -> 渠道配置),填写各支付渠道所需数据。

集成 SDK

集成 iOS 环境

  1. 重要:先安装 maxleap-react-native, 参照 MaxLeap RN 开发文档

  2. 安装 maxpay-react-native

    npm install --save maxpay-react-native
    
  3. 打开 Finder,找到本项目的根目录,使用 Xcode 打开 iOS 工程(双击 .xcodeproj 文件即可),然后导航到 /node_modules/maxpay-react-native/ios/lib 目录,把该目录下的 frameworks 都拖到 Xcode 工程中

  4. 添加 Framework Search Paths

    在 Xcode 中,导航到 Targets -> YourAppName -> “Build Settings",找到 “Framework Search Paths” 一项,添加下面这个路径:

    $(SRCROOT)/../node_modules/maxpay-react-native/ios/lib

  5. 此外,使用个平台进行支付还需要配置 Xcode 项目,请参阅支付文档的手动安装第4步以后的部分

集成 Android 环境

  1. 按照 MaxLeap 文档 添加项目依赖。

  2. 修改父工程目录下的 build.gradle 文件(与 settings.gradle 位于同级目录)。

    repositories {
        flatDir{
            dirs '../../node_modules/maxpay-react-native/dist/android'
        }
    }
    
  3. 修改应用目录下的 build.gradle 文件,添加以下依赖

    dependencies {
        compile(name:'maxpay-react-native', ext:'aar')
    }
    
  4. 修改工程的主 Activity 文件。

     @Override
    protected void onCreate(Bundle savedInstanceState) {
        MaxLeap.initialize(this, APP_ID, API_KEY, MaxLeap.REGION_CN);
        super.onCreate(savedInstanceState);
    }
    
    @Override
    protected List<ReactPackage> getPackages() {
        return Arrays.<ReactPackage>asList(
                new MainReactPackage(),
                new MLPayReactPackage()
        );
    }
    

应用内社交 npm version

集成 SDK

  1. 重要:先安装 maxleap-react-native, 参照 MaxLeap RN 开发文档

  2. 安装 maxleap-social-react-native

    npm install --save maxleap-social-react-native
    
  3. 打开 Finder,找到本项目的根目录,使用 Xcode 打开 iOS 工程(双击 .xcodeproj 文件即可),然后导航到 /node_modules/maxleap-social-react-native/ios/lib 目录,把该目录下的 frameworks 都拖到 Xcode 工程中

  4. 添加 Framework Search Paths

    在 Xcode 中,导航到 Targets -> YourAppName -> “Build Settings",找到 “Framework Search Paths” 一项,添加下面这个路径:

    $(SRCROOT)/../node_modules/maxleap-social-react-native/ios/lib

集成 Android 环境

  1. 按照 MaxLeap 文档 添加项目依赖。

  2. 修改父工程目录下的 build.gradle 文件(与 settings.gradle 位于同级目录)。

    repositories {
        flatDir{
            dirs '../../node_modules/maxleap-social-react-native/dist/android'
        }
    }
    
  3. 修改应用目录下的 build.gradle 文件,添加以下依赖

    dependencies {
        compile(name:'maxleap-social-react-native', ext:'aar')
    }
    
  4. 修改工程的主 Activity 文件。

     @Override
    protected void onCreate(Bundle savedInstanceState) {
        MaxLeap.initialize(this, APP_ID, API_KEY, MaxLeap.REGION_CN);
        super.onCreate(savedInstanceState);
    }
    
    @Override
    protected List<ReactPackage> getPackages() {
        return Arrays.<ReactPackage>asList(
                new MainReactPackage(),
                new MLInAppSocialReactPackage()
        );
    }
    

社交分享 npm version

集成 SDK

集成 iOS 环境

  1. 重要:先安装 maxleap-react-native, 参照 MaxLeap RN 开发文档

  2. 安装 maxshare-react-native

    npm install --save maxshare-react-native
    
  3. 打开 Finder,找到本项目的根目录,使用 Xcode 打开 iOS 工程(双击 .xcodeproj 文件即可),然后导航到 /node_modules/maxshare-react-native/ios/lib 目录,把该目录下的 frameworks 都拖到 Xcode 工程中

  4. 添加 Framework Search Paths

    在 Xcode 中,导航到 Targets -> YourAppName -> “Build Settings",找到 “Framework Search Paths” 一项,添加下面这个路径:

    $(SRCROOT)/../node_modules/maxshare-react-native/ios/lib

  5. 重要:此外还需要在 Xcode 中配置各社交平台分享环境,请参阅MaxLeap 社交分享文档

集成 Android 环境

  1. 按照 MaxLeap 文档 添加项目依赖。

  2. 修改父工程目录下的 build.gradle 文件(与 settings.gradle 位于同级目录)。

    repositories {
        flatDir{
            dirs '../../node_modules/maxshare-react-native/dist/android'
        }
    }
    
  3. 修改应用目录下的 build.gradle 文件,添加以下依赖

    dependencies {
        compile(name:'maxshare-react-native', ext:'aar')
    }
    
  4. 修改工程的主 Activity 文件。

     @Override
    protected void onCreate(Bundle savedInstanceState) {
        MaxLeap.initialize(this, APP_ID, API_KEY, MaxLeap.REGION_CN);
        super.onCreate(savedInstanceState);
    }
    
    @Override
    protected List<ReactPackage> getPackages() {
        return Arrays.<ReactPackage>asList(
                new MainReactPackage(),
                new MLInAppSocialReactPackage()
        );
    }
    

API

share([object])

只接受一个参数,类型为 object。 返回一个 promise 对象,如果成功调用了第三方平台的分享接口,返回改平台的 ID

参数键值说明:

值类型描述
typestring分享内容的类型,目前支持五种类型:
text, image, webpage, music, video
titlestring分享内容的标题
detailstring详细描述
webpageURLstring一个网页链接地址
previewImagePathstring预览图片路径,本地文件路径
attachmentURLstring附件链接地址
latitudenumber纬度
longitudenumber经度
rectobject{x: 120, y: 30, width: 20, height: 30}
触发分享操作的按钮在屏幕中的位置,iPad 上有效,用来在按钮附近以 popover 的形式显示分享界面

使用方法

注意: 微信 SDK 限制缩略图大小为不超过 32k,如果点击微信按钮后得到分享失败的错误提示,请检查相关数据的规格是否合乎微信 SDK 的要求。更多信息请查阅微信开发者须知

导入模块:

import share from 'maxshare-react-native';
  • 分享文本

    let textItem = {
        type: 'text',
        detail: '文字内容', // required
        // for iPad
        rect: {x: 120, y: 30, width: 20, height: 30}
    }
    
    share(textItem).then(platform => {
      alert('share text via platform: ' + platform)
    })
    
  • 分享图片

    let imgItem = {
        type: 'image',
        title: '图片标题', // optional, 只有QQ支持
        detail: '图片描述', // optional, 只有QQ支持
        attachmentURL: '图片链接', // required,支持 fileURL 和 远程图片链接
        previewImagePath: '预览图片文件路径', // optional, 只有QQ支持
        // for iPad
        rect: {x: 120, y: 30, width: 20, height: 30}
    }
    
    share(imgItem).then(platform => {
      alert('share an image via platform: ' + platform)
    })
    
  • 分享网页

    let webItem = {
        type: 'webpage',
        title: '网页标题',
        detail: '网页描述',
        webpageURL: '网页链接',
        previewImagePath: '预览图片文件路径',
        // for iPad
        rect: {x: 120, y: 30, width: 20, height: 30}
    }
    
    share(webItem).then(platform => {
      alert('share a webpage via platform: ' + platform)
    })
    
  • 分享音乐

    let musicItem = {
        type: 'music',
        title: '音乐标题',
        detail: '音乐描述',
        webpageURL: '音乐网页链接', // 微博,微信支持,QQ不支持
        attachmentURL: '音乐数据流链接',
        previewImagePath: '预览图片文件路径',
        // for iPad
        rect: {x: 120, y: 30, width: 20, height: 30}
    }
    
    share(musicItem).then(platform => {
      alert('share a music via platform: ' + platform)
    })
    
  • 分享视频

    let videoItem = {
        type: 'music',
        title: '视频标题',
        detail: '视频描述',
        webpageURL: '视频网页链接',   // 微信,微博支持,QQ 不支持
        attachmentURL: '视频数据流链接', // QQ, 微博支持,微信不支持
        previewImagePath: '预览图片文件路径',
        // for iPad
        rect: {x: 120, y: 30, width: 20, height: 30}
    }
    
    share(videoItem).then(platform => {
      alert('share a video via platform: ' + platform)
    })
    

在线参数

简介

什么是在线参数

每个应用在云端都有一个对应的MLConfig对象,用以存储该应用的参数。Cloud Config服务帮助您访问和操作云端参数。您可以通过 Console 在 MaxLeap 中配置应用参数,并且使用 iOS/Android SDK 读取云端的参数。

在线参数中添加参数

您可以通过Console向Cloud Config中增添应用参数。新建云端参数时,您需要指定该参数的以下属性:

属性名
Parameter参数名
Type参数类型
Value参数的值

您还可以为不同的Segment设置不同的参数值。

获取 currentConfig 对象

import ML from 'maxleap-react-native'

ML.Config.currentConfig().then(currentConfig => {
    console.log('current config is ' + currentConfig)
})

手动刷新 currentConfig

在每次 app 进入前台时,SDK 会自动刷新 currentConfig

也可以调用以下代码手动刷新所有云参数

ML.Config.fetchConfig()
.then(config => {
    // this config is currentConfig
});

或者刷新某几个参数

ML.Config.fetchConfig(['key1', 'key2'])
.then(config => {
    // this config is currentConfig
})

刷新后,如果有参数的值发生变化,就会触发一个 configValueChangedEvent.

监听在线参数变化

JavaScript 代码可以订阅参数更新事件 configValueChangedEvent.

import { NativeAppEventEmitter } from 'react-native';

let subscription = NativeAppEventEmitter.addListener(
  ML.Config.configValueChangedEvent,
  (changes) => console.log(changes)
);
...
// Don't forget to unsubscribe, typically in componentWillUnmount
subscription.remove();

数据分析

简介

什么是 MaxLeap 数据分析服务

MaxLeap 数据分析服务通过客户端及 Cloud Data,收集页面及用户的各种数据,并在 MaxLeap 中进行专业分析,最终生成面向运营者的报表。

启用服务

安装SDK完成后,MaxLeap 服务将自动帮助您追踪应用内的一些数据。自动收集的数据包括:

  1. 终端信息
  2. 应用启动和退出
  3. 应用崩溃等异常信息

MaxLeap 数据分析服务的默认状态为开启

页面访问路径统计

可以统计每个 View 停留时长,请确保配对使用,而且这些 view 之间不要有嵌套关系:

ML.Analytics.beginLogPageView(pagename)
ML.Analytics.endLogPageView(pagename)

自定义事件

自定义事件可以实现在应用程序中埋点,以纪录用户的点击行为并且采集相应数据。

字段说明

字段名类型描述
eventIdString事件名
keyString事件参数
valueString事件参数的值

请注意, 自定义事件名 (event_id) 请尽量保持其为静态值, 否则可能出现数目庞大的自定义事件列表, 而无法达到了解与分析用户行为的目的.

统计某事件发生次数

ML.Analytics.trackEvent("event_id");

统计事件属性被触发次数

考虑事件在不同属性上的取值,可以调用如下方法:

ML.Analytics.trackEvent(eventId, parameters={}, count=1)

parameters 为当前事件的属性和取值(键值对) count 为事件发生次数,可以用来减少发送的数据量

示例:统计电商应用中“购买”事件发生的次数,以及购买的商品类型及数量,那么在购买的函数里调用:

let parameters = {type: 'book', quantity: '3'}
ML.Analytics.trackEvent('purchase', parameters, 1)

推送营销

简介

什么是 MaxLeap 推送营销服务

推送营销服务是 MaxLeap 提供的营销和信息发布功能。目前提供两种消息模式:推送消息 和 应用内消息。您可以通过推送消息方式向指定人群推送消息,也可以通过应用内消息,在应用内向有某种行为的用户显示特定内容。您还可以在消息中设置用户点击后的目标 Activity。消息的创建,设置和发送均在Console中完成。

集成

推送营销集成方式跟 native 集成方式一样。

iOS 集成请参考 iOS 推送营销指南 Android 集成请参考 Android 推送营销指南

用户支持 npm version

简介

用户支持服务是 MaxLeap 为开发者提供的一套标准应用客服方案。在客户端,此方案提供完整的 FAQ 的显示页面及用户反馈对话页面。在Console端,用户支持服务提供FAQ 的管理及用户反馈的处理界面。

集成 SDK

集成 iOS 环境

  1. 重要:先安装 maxleap-react-native, 参照 MaxLeap 开发文档

  2. 安装 maxleap-helpcenter-react-native

    npm install --save maxleap-helpcenter-react-native
    
  3. 打开 Finder,找到本项目的根目录,使用 Xcode 打开 iOS 工程(双击 .xcodeproj 文件即可),然后导航到 /node_modules/maxleap-helpcenter-react-native/ios/lib 目录,把该目录下的 frameworks 都拖到 Xcode 工程中

  4. 添加 Framework Search Paths

    在 Xcode 中,导航到 Targets -> YourAppName -> “Build Settings",找到 “Framework Search Paths” 一项,添加下面这个路径:

    $(SRCROOT)/../node_modules/maxleap-helpcenter-react-native/ios/lib 并设置为recursive

集成 Android 环境

  1. 按照 MaxLeap 文档 添加项目依赖。

  2. 修改父工程目录下的 build.gradle 文件(与 settings.gradle 位于同级目录)。

    repositories {
        flatDir{
            dirs '../../node_modules/maxleap-helpcenter-react-native/dist/android'
        }
    }
    
  3. 修改应用目录下的 build.gradle 文件,添加以下依赖

    dependencies {
        compile(name:'maxleap-helpcenter-react-native', ext:'aar')
    }
    
  4. 修改工程的主 Activity 文件。

     @Override
    protected void onCreate(Bundle savedInstanceState) {
        MaxLeap.initialize(this, APP_ID, API_KEY, MaxLeap.REGION_CN);
        super.onCreate(savedInstanceState);
    }
    
    @Override
    protected List<ReactPackage> getPackages() {
        return Arrays.<ReactPackage>asList(
                new MainReactPackage(),
                new MLHelpCenterReactPackage()
        );
    }
    

API

ShowFAQs()

弹出 FAQs 界面, 此界面右上角会有一个按钮 Contact Us, 点击会跳到用户反馈界面

showConversation()

直接弹出用户反馈界面

示例

import React, { Component } from 'react';
import ReactNative, { View, Text, TouchableHighlight } from 'react-native';
import HelpCenter from 'maxleap-helpcenter-react-native';

const styles = {
  container: {
    justifyContent: 'center',
    flex: 1
  },
  btnText: {
    textAlign: 'center',
    fontSize: 18
  },
  btn: {
    height: 50,
    justifyContent: 'center'
  }
};

export default class Main extends Component {
  render() {
    return (
      <View style={styles.container}>
        <TouchableHighlight onPress={()=>HelpCenter.showFAQs()}
                            underlayColor={'#32BE78'}
                            style={styles.btn}>
          <Text style={styles.btnText}>
            Help
          </Text>
        </TouchableHighlight>
        <TouchableHighlight onPress={()=>HelpCenter.showConversation()}
                            underlayColor={'#F2BE78'}
                            style={styles.btn}>
          <Text style={styles.btnText}>
            Contact Us
          </Text>
        </TouchableHighlight>
      </View>
    );
  }
}

自定义 UI

请参考 iOS 用户支持指南Android 用户支持指南