MaxIM-Javascript V4

警告: 旧版SDK(v3.x.x)仍可使用, 但已经不再维护, 如需使用最新功能, 请尽快迁移到V4版

如何使用

您可以使用如下方式集成SDK:

使用NPM

加载方式为CMD, 适用于NodeJS, 或者webpack等。使用范例如下。

首先用npm安装模块:

$ npm install maxleap-im --save

然后如下方式加载:

var IM = require('maxleap-im');
var options = {
  app: 'YOUR_APP_ID', // 应用ID, 参见应用设置的ApplicationID.
  key: 'YOUR_API_KEY'  // 应用密钥, 参见应用设置的ClientKey.
};
var im = IM(options);
// ......

使用Bower(Deprecated)

加载方式为AMD, 浏览器端推荐。使用范例如下。

首先通过bower来安装依赖:

$ bower install maxleap-im --save

接着使用requirejs来载入:

// 初始化requirejs

require.config({
  paths: {
    'socket.io-client': 'bower_components/socket.io-client/socket.io',
    'axios': 'bower_components/axios/dist/axios',
    'maxleap-im': 'bower_components/maxleap-im/dist'
  }
});

require(['maxleap-im/im'],function(IM){
  var opts = {
    app: 'YOUR_APP_ID',
    key: 'YOUR_APP_KEY'
  };

  var im = IM(opts); // 或者 ML.im(opts)
   // ......
});

入门

以下为入门样例代码, 更高级的功能请参考下文的API文档。

    // 通过上文的方式初始化MaxIM实例
    im.login()
      .simple('12345678')
      .onFriendMessage(function(friendid,message){
        console.log('message from friend %s: %s', friendid, message.content.body);
      })
      .onAck(function(ack,ts){
        console.log('get message ack %d: time=%d.',ack,ts);
      })
      .ok(function(error,session,context){
        if(error){
          console.error('login failed: %s',error.message);
          return;
        }

        context.listFriends(function(err,friends){
            // process response
        });

        // send text message.
        session
          .say('hello world!')
          .ack(12345)
          .asText()
          .toFriend('87654321')
          .ok();

        // upload image attachment and send it as image message.
        context.attachment(YOUR_IMG_FILE)
          .ok(function(err,urls){
              if(err){
                  console.error('upload file failed: %s',err.message);
                  return;
              }

              var origin= urls[0], thumb = urls[1];
              session.say(origin,thumb).asImage().toGroup('group1234')
                .ok(function(error){
                  session.close(function(error){
                    if(error){
                      console.error('logout failed: %s',error.message);
                      return;
                    }
                    console.log('goodbye!');
                  });
                });
          });

    });

    im.admin().create()
      .room()
      .attribute('name','OP fans')
      .attribute('location','Shanghai')
      .attribute('star',5)
      .members('cat','dog','fish')
      .ok(function(err,roomid){
          if(err){
            console.error('create room failed: %s',err.message);
            return;
          }
          console.log('create room success: %s',roomid);
      });

API文档

IM(opts:Object):MaxIM

调用后对于给定的设置项初始化一个MaxIM实例, 该实例可以全局用于控制各种内部服务操作。opts设置项包含以下配置:

MaxIM

核心入口类

MaxIM#login():Login

初始化并返回一个登录器。登录器可被用于进一步登录操作。

MaxIM#passenger(passengerid:string):PassengerBuilder

初始化并返回一个访客构造器。该构造器可以用于进一步访客模式登录操作。

MaxIM#admin():Admin

初始化并返回一个管理器实例。管理器拥有最高级别的控制权限, 通常被用于一些系统级的控制操作。

Login

登录器, 可进行登录设置并创建会话。

Login#simple(userid:string):SessionBuilder

使用简单方式登录并返回一个session构造器实例。该登录方式仅需要一个用户ID唯一标识即可。安全级别低, 建议使用高级别的登录方式。

Login#byMaxleapUser(username:string,password:string):SessionBuilder

使用MaxLeap自带的账号系统登录并返回一个session构造器实例。该登录方式比较安全, 推荐使用, 您只需传统的用户名+密码方式即可登录。

如果您对MaxLeap自带账号系统不太熟悉, 这里是文档传送门。

Login#byPhone(phone:string,verify:string):SessionBuilder

使用MaxLeap的短信验证方式登录并返回一个session构造器实例。该登录方式比较安全, 推荐使用。关于如何使用MaxLeap短信验证, 请参阅传送门。

SessionBuilder

session构造器, 用于初始化session设置, 绑定各种事件, 并进行登录调用。 该类中的设置接口使用流畅接口风格, 您可以进行链式设置并最后调用ok进行最终提交创建。

SessionBuilder#setNotifyAll(enable:boolean):SessionBuilder

启用在线/离线通知给所有人(默认禁用)。启用后该用户的上下线状态对于非好友的应用内用户也会进行状态通知。该特性可以被用于例如客服，专家问答系统等。

SessionBuilder#setInstallation(installation:string):SessionBuilder

设置应用安装ID。应用安装ID唯一标识一台设备的一次应用安装, 该标识将被用于离线消息推送时确认唯一身份。

SessionBuilder#onFriendMessage(callback:(userid,message)=>void):SessionBuilder

绑定好友消息源。绑定该事件后, 所有来自您的好友的消息都会回调。其中回调句柄的参数用法:

SessionBuilder#onGroupMessage(callback:(groupid,memberid,message)=>void):SessionBuilder

绑定群组消息源。绑定该事件后, 所有来自您当前已加入的群组内消息都会进行回调。其中回调句柄的参数用法:

SessionBuilder#onRoomMessage(callback:(roomid,memberid,message)=>void):SessionBuilder

绑定聊天室消息源。绑定该事件后, 所有来自您当前已加入的聊天室内的消息都会进行回调。其中回调句柄的参数用法为:

SessionBuilder#onPassengerMessage(callback:(passengerid,message)=>void):SessionBuilder

绑定来自访客的消息源。绑定该事件后, 所有来自未注册临时访客发送给您的消息都会进行回调。其中回调句柄的参数用法为:

SessionBuilder#onStrangerMessage(callback:(strangerid,message)=>void):SessionBuilder

绑定来自陌生人的消息源。绑定该事件后, 所有来自陌生人发送给您的消息都会进行回调。其中回调句柄的参数用法:

SessionBuilder#onSystemMessage(callback:(message)=>void):SessionBuilder

绑定系统消息源。绑定该事件后, 所有的系统消息都会进行回调。其中回调句柄的参数用法:

SessionBuilder#onYourself(callback:(message)=>void):SessionBuilder

当您在多个终端登录后, 您可以绑定来自其他终端的另一个"你"发送的消息。其中回调句柄的参数用法:

SessionBuilder#onFriendOnline(callback:(friendid)=>void):SessionBuilder

绑定好友上线通知。绑定事件后, 当您的某个好友上线时您会收到通知并回调。其中回调句柄的参数用法:

SessionBuilder#onFriendOffline(callback:(friendid)=>void):SessionBuilder

绑定好友离线通知。绑定事件后, 当您的某个好友离线时您会收到通知并回调。其中回调句柄的参数用法:

SessionBuilder#onStrangerOnline(callback:(strangerid)=>void):SessionBuilder

绑定陌生人上线通知。绑定事件后, 当某个非好友用户上线时您会收到通知并回调, 注意: 仅当对方setNotifyAll设置为true时才会生效。其中回调句柄的参数用法:

SessionBuilder#onStrangerOffline(callback:(strangerid)=>void):SessionBuilder

绑定陌生人离线通知。绑定事件后, 当某个非好友用户离线时您会收到通知并回调, 注意: 仅当对方setNotifyAll设置为true时才会生效。其中回调句柄的参数用法:

SessionBuilder#onAck(callback:(ack,ts)=>void):SessionBuilder

绑定消息回执响应。绑定事件后, 当消息发送成功后您会收到通知并回调, 注意: 仅当构建消息时设置了ack才会生效。其中回调句柄的参数用法:

SessionBuilder#ok(callback:(error,session,context)=>void)

结束退出构造器调用链, 您可在回调句柄中获取到session创建结果。回调句柄的参数用法:

Session

用户登录会话, 该会话与服务器维持一个长连接, 您可以通过该类内的API进行核心的消息收发。

Session#current():string

返回当前登录用户ID。

Session#say(text:string,remark?:string):MessageBuilder

新建一个消息构造器实例。消息构造器可以用于构建设置并最终发送消息。text为您的消息文本(必填项), remark为本条消息的备注信息(可选项)。

Session#close(callback:(error)=>void)

关闭并销毁用户登录会话。当关闭失败时回调参数中会返回error对象。

MessageBuilder

消息构造器, 用于构造并最终发送消息。

MessageBuilder#asText():MessageBuilder

将本条消息媒体类型设置为纯文本并返回原实例。

MessageBuilder#asImage():MessageBuilder

将本条消息媒体类型设置为图片并返回原实例。

MessageBuilder#asAudio():MessageBuilder

将本条消息媒体类型设置为音频并返回原实例。

MessageBuilder#asVideo():MessageBuilder

将本条消息媒体类型设置为视频并返回原实例。

MessageBuilder#disablePush():MessageBuilder

设置本条消息禁用推送功能并返回原实例。

MessageBuilder#setPushPrefix(prefix:string):MessageBuilder

设置本条消息的推送文本前缀并返回原实例。

MessageBuilder#setPushSuffix(suffix:string):MessageBuilder

设置本条消息的推送文本后缀并返回原实例。

MessageBuilder#setPushTextOverwrite(overwrite:string):MessageBuilder

覆盖设置本条消息的推送消息文本, 设置后原本的消息文本将会被替换。

MessageBuilder#setPushSound(sound:string):MessageBuilder

设置本条消息的推送铃声并返回原实例。注意: 仅限IOS设备

MessageBuilder#setPushContentAvailable(contentAvailable:boolean):MessageBuilder

设置本条消息的content-avaliable并返回原实例。注意: 仅限IOS设备

MessageBuilder#toAll():MessageLauncher

设置本条消息的发送对象为所有人并返回消息发射器。注意: 仅限Admin使用, 用于向所有人发送系统消息!!!

MessageBuilder#toUser(userid:string):MessageLauncher

设置本条消息的发送对象为单个普通用户并返回消息发射器。注意: 仅限Admin和访客模式使用!!!

MessageBuilder#toFriend(friendid:string):MessageLauncher

设置本条消息的发送对象为好友并返回消息发射器。friendid为好友的用户ID。注意: 仅限普通用户登录模式使用!!!

MessageBuilder#toGroup(groupid:string):MessageLauncher

设置本条消息的发送对象为群组并返回消息发射器。groupid为群组ID。注意: 仅限Admin和普通用户登录模式使用!!!

MessageBuilder#toRoom(roomid:string):MessageLauncher

设置本条消息的发送对象为聊天室并返回消息发射器。roomid为聊天室ID。注意: 仅限Admin和普通用户登录模式使用!!!

MessageBuilder#toPassenger(passengerid:string):MessageLauncher

设置本条消息的发送对象为访客并返回消息发射器。passengerid为访客ID。注意: 仅限普通用户登录模式使用!!!

MessageBuilder#toStranger(strangerid:string):MessageLauncher

设置本条消息的发送对象为陌生人并返回消息发射器。strangerid为陌生人用户ID。注意: 仅限普通用户登录模式使用!!!

MessageLauncher

消息发射器, 提交并最后发射消息。

MessageLauncher#ok(callback:(error)=>void):Session|PassengerSession

发射消息并返回用户登录会话。当发射发生错误时, 回调句柄中的error对象会包含错误详情。

Context

用户上下文对象, 封装了针对当前登录用户的一些通用操作。

Context#listFriends(callback:(error,friends)=>void):Context

列出当前用户的好友列表。回调函数的参数说明如下:

Context#listGroups(callback:(error,groups)=>void):Context

列出当前已加入的群组列表。回调函数的参数说明如下:

Context#listRooms(callback:(error,rooms)=>void):Context

列出当前已加入的聊天室列表。回调函数的参数说明如下:

Context#listStrangers(callback:(error,strangers)=>void,skip:number,limit:number):Context

列出当前有关联的陌生人列表。skip和limit为可选项, 用于控制分页, 分别表示跳过记录数和返回记录条数。

回调函数callback的参数说明如下:

Context#listTalkings(endTimestamp:number,size:number):TalkingBuilder

返回一个聊天记录查询器实例。该查询器可以被用于进一步的调用并最终获取聊天记录。方法参数说明如下:

Context#joinFriend(userid:string,callback:(error)=>void):Context

添加好友。userid为被添加好友的用户ID。 回调方法参数说明如下:

Context#joinGroup(groupid:string,callback:(error)=>void):Context

加入指定群组。groupid为要加入的群组ID。 回调方法参数说明如下:

Context#joinRoom(roomid:string,callback:(error)=>void):Context

加入指定聊天室。roomid为要加入的聊天室ID。 回调方法参数说明如下:

Context#leaveFriend(userid:string,callback:(error)=>void):Context

解除好友关系。userid为被解除好友的用户ID。 回调方法参数说明如下:

Context#leaveGroup(groupid:string,callback:(error)=>void):Context

离开指定群组。groupid为要离开的群组ID。 回调方法参数说明如下:

Context#leaveRoom(roomid:string,callback:(error)=>void):Context

离开指定聊天室。roomid为要离开的聊天室ID。 回调方法参数说明如下:

Context#setMyAttributes(attributes:object,overwrite:boolean,callback:(error)=>void):Context

设置我的自定义属性。参数说明如下:

回调方法callback的参数说明如下:

Context#setMyAttribute(name:string,value:object,callback:(error)=>void):Context

设置我的单个自定义属性。参数说明如下:

回调方法callback的参数说明如下:

Context#getMyAttributes(callback:(error,attributes)=>void):Context

获取我的自定义属性表。其中回调方法的参数说明如下:

Context#getMyAttribute(name:string,callback:(error,attribute)=>void):Context

获取我的单个自定义属性。参数name为属性名, 回调方法callback的参数说明如下:

Context#search(query:object,skip:number,limit:number,sort:string[]):SearchBuilder

本方法继承自父类, 参见Common中对应的方法。

Context#load(id:string):[LoadBuilder])(#loadbuilder)

本方法继承自父类, 参见Common中对应的方法。

Context#getAttributes(id:string,atttibuteName:string):GetAttributesBuilder

本方法继承自父类, 参见Common中对应的方法。

Context#attachment(attachment:File|Blob):AttachmentBuilder

本方法继承自父类, 参见Common中对应的方法。

TalkingBuilder

聊天记录查询构造器。

TalkingBuilder#ofFriend(friendid:string,callback:(error,records)=>void):Context

查询与指定好友的聊天记录, 并返回起始用户上下文。其中参数friendid指定好友的用户ID, 回调方法callback的参数定义如下:

TalkingBuilder#ofGroup(groupid:string,callback:(error,records)=>void):Context

查询与群组聊天记录, 并返回起始用户上下文。其中参数groupid指定群组ID, 回调方法callback的参数定义如下:

TalkingBuilder#ofStranger(strangerid:string,callback:(error,records)=>void):Context

查询与指定陌生人的聊天记录, 并返回起始用户上下文。其中参数strangerid指定陌生人的用户ID, 回调方法callback的参数定义如下:

TalkingBuilder#ofPassenger(passengerid:string,callback:(error,records)=>void):Context

查询与指定访客的聊天记录, 并返回起始用户上下文。其中参数passengerid为访客ID, 回调方法callback的参数定义如下:

PassengerBuilder

访客构造器。

PassengerBuilder#attribute(name:string,value:object):PassengerBuilder

设置访客属性。

PassengerBuilder#onUserMessage(callback:(userid,message)=>void):PassengerBuilder

绑定来自某个用户发送给您的消息。回调函数参数说明如下:

PassengerBuilder#onSystemMessage(callback:(message)=>void):PassengerBuilder

绑定来自管理员发送给您的系统消息。回调函数参数说明如下:

PassengerBuilder#onStrangerOnline(callback:(strangerid)=>void):PassengerBuilder

绑定来自陌生人上线通知。回调函数参数说明如下:

PassengerBuilder#onStrangerOffline(callback:(strangerid)=>void):PassengerBuilder

绑定来自陌生人下线通知。回调函数参数说明如下:

PassengerBuilder#onAck(callback:(ack,ts)=>void):PassengerBuilder

绑定消息回执响应。绑定事件后, 当消息发送成功后您会收到通知并回调, 注意: 仅当构建消息时设置了ack才会生效。其中回调句柄的参数用法:

PassengerBuilder#ok(callback:(error,session,context)=>void)

结束链式调用提交并登录。回调函数参数说明如下:

PassengerSession

访客登录会话。维持一次访客登录连接。提供核心的消息收发功能。

PassengerSession#say(text:string,remark:string):MessageBuilder

返回一个消息构建器实例。

PassengerSession#close(callback:(error)=>void)

退出并关闭访客会话。

PassengerContext

访客用户上下文。封装了针对当前登录访客的常用操作。

PassengerContext#current():string

返回当前登录的访客ID。

PassengerContext#search(query:object,skip:number,limit:number,sort:string[]):SearchBuilder

本方法继承自父类, 参见Common中对应的方法。

PassengerContext#load(id:string):[LoadBuilder])(#loadbuilder)

本方法继承自父类, 参见Common中对应的方法。

PassengerContext#getAttributes(id:string,atttibuteName:string):GetAttributesBuilder

本方法继承自父类, 参见Common中对应的方法。

PassengerContext#attachment(attachment:File|Blob):AttachmentBuilder

本方法继承自父类, 参见Common中对应的方法。

Admin

管理类, 包含最高权限的一些操作封装。

Admin#say(text:string,remark:string):MessageBuilder

新建一个系统消息构造器实例。系统消息构造器可以用于构建设置并最终发送消息。text为您的消息文本(必填项), remark为本条消息的备注信息(可选项)。

Admin#setAttributes(attributes:Object,overwrite:boolean):AttributeBuilder

新建一个属性构造器实例。

Admin#create():CreateCommand

新建一个空白创建命令实例。您可以通过该命令来生成各种对象。

Admin#destroy():DestroyCommand

新建一个空白的销毁命令实例。您可以通过该销毁命令来销毁各种对象。

Admin#appendMembers(first:string,others:string...):MemberAppendCommand

新建一个成员追加命令。

Admin#removeMembers(first:string,others:string...):MemberRemoveCommand

新建一个成员移除命令。

Admin#search(query:object,skip:number,limit:number,sort:string[]):SearchBuilder

本方法继承自父类, 参见Common中对应的方法。

Admin#load(id:string):[LoadBuilder])(#loadbuilder)

本方法继承自父类, 参见Common中对应的方法。

Admin#getAttributes(id:string,atttibuteName:string):GetAttributesBuilder

本方法继承自父类, 参见Common中对应的方法。

Admin#attachment(attachment:File|Blob):AttachmentBuilder

本方法继承自父类, 参见Common中对应的方法。

AttributeBuilder

属性构造器, 用于设置对象自定义属性。

AttributeBuilder#forUser(userid:string,callback:(error)=>void):Admin

将设置的属性应用于指定的用户。

AttributeBuilder#forGroup(groupid:string,callback:(error)=>void):Admin

将设置的属性应用于指定的群组。

AttributeBuilder#forRoom(roomid:string,callback:(error)=>void):Admin

将设置的属性应用于指定的聊天室。

CreateCommand

对象创建命令。

CreateCommand#group(owner:string):GroupBuilder

新建并返回一个群组构造器, owner为群组创建者ID。

CreateCommand#room():RoomBuilder

新建并返回一个聊天室构造器。

GroupBuilder

群组构造器, 用于生成新的群组。

GroupBuilder#attribute(key:string,value:Object):GroupBuilder

设置群组属性。

GroupBuilder#members(first:string,others:string...):GroupBuilder

设置群组成员。

GroupBuilder#ok(callback:(error,groupid)=>void):Admin

结束链式调用, 提交并创建群组并返回起始Admin对象。

RoomBuilder

聊天室构造器, 用于生成新的聊天室。

RoomBuilder#attribute(key:string,value:Object):RoomBuilder

设置聊天室属性。

RoomBuilder#members(first:string,others:string...):RoomBuilder

设置聊天室成员。

RoomBuilder#ok(callback:(error,roomid)=>void):Admin

结束链式调用, 提交并创建聊天室并返回起始Admin对象。

DestroyCommand

对象销毁命令。用于销毁指定对象。

DestroyCommand#group(groupid:string):GroupDestroy

销毁群组。

DestroyCommand#room(roomid:string):RoomDestroy

销毁聊天室。

GroupDestroy

群组销毁器。

GroupDestroy#ok(callback:(error)=>void):Admin

结束链式调用, 提交销毁群组并返回起始Admin对象。

RoomDestroy

聊天室销毁器。

RoomDestroy#ok(callback:(error)=>void):Admin

结束链式调用, 提交销毁聊天室并返回起始Admin对象。

MemberAppendCommand

追加成员命令。用于向指定对象追加成员。

MemberAppendCommand#intoGroup(groupid:string,callback:(error)=>void):Admin

结束链式调用, 将成员加入至群组并返回原始Admin实例。

MemberAppendCommand#intoRoom(roomid:string,callback:(error)=>void):Admin

结束链式调用, 将成员加入至聊天室内并返回原始Admin实例。

MemberRemoveCommand

移除成员命令。用于移除指定对象内的成员。

MemberRemoveCommand#fromGroup(groupid:string,callback:(error)=>void):Admin

结束链式调用, 移除群组成员并返回原始Admin实例。

MemberRemoveCommand#fromRoom(roomid:string,callback:(error)=>void):Admin

结束链式调用, 移除聊天室成员并返回原始Admin实例。

Common

通用操作抽象类, 仅作为Context和Admin的父类。用于封装最基础的只读业务操作。

Common#search(query:object,skip:number,limit:number:sort:string[]):SearchBuilder

创建一个搜索器实例。搜索器可以被用来返回搜索结果。参数定义如下:

Common#load(id:string):LoadBuilder

创建一个载入器实例。载入器可以被用于载入特定对象。参数id表示被载入对象的标识ID。

Common#getAttributes(id:string,attributeName:string):GetAttributesBuilder

返回一个属性查询器。属性查询器可以被用来返回属性对象。参数用法如下:

Common#attachment(attachment:File|Blob):AttachmentBuilder

创建并返回一个附件上传器。attachment可以是一个文件或者二进制块对象。

GetAttributesBuilder

属性查询器。

GetAttributesBuilder#forUser(callback:(error,result)=>void)

返回用户的自定义属性。回调方法参数说明如下:

GetAttributesBuilder#forGroup(callback:(error,result)=>void)

返回群组的自定义属性。回调方法参数说明如下:

GetAttributesBuilder#forRoom(callback:(error,result)=>void)

返回聊天室的自定义属性。回调方法参数说明如下:

AttachmentBuilder

附件上传器。当调用ok方法时会进行上传操作。

AttachmentBuilder#ok(callback:(error,uris)=>void)

提交执行上传。回调方法的参数说明如下:

LoadBuilder

对象载入器。

LoadBuilder#forUser(callback:(error,user)=>void)

载入指定用户。回调函数的参数说明如下:

LoadBuilder#forGroup(callback:(error,group)=>void)

载入指定群组。回调函数的参数说明如下:

LoadBuilder#forRoom(callback:(error,room)=>void)

载入指定聊天室。回调函数的参数说明如下:

LoadBuilder#forPassenger(callback:(error,passenger)=>void)

载入指定访客。回调函数的参数说明如下:

SearchBuilder

搜索器

SearchBuilder#forUsers(callback:(error,users)=>void)

搜索用户。回调函数参数如下:

SearchBuilder#forGroups(callback:(error,groups)=>void)

搜索群组。回调函数参数如下:

SearchBuilder#forRooms(callback:(error,rooms)=>void)

搜索聊天室。回调函数参数如下:

BasicMessage

基础消息结构体。属性说明如下:

Content

消息正文结构体。属性说明如下:

ParrotError

错误异常通用类, 继承自Error对象。

Friend

好友详情结构体。属性说明如下:

ChatRecord

通用聊天记录结构体。属性说明如下:

Group

群组详情结构体。属性说明如下:

Room

聊天室详情结构体。属性说明如下:

User

用户信息结构体。属性说明如下:

Stranger

陌生人信息结构体。属性说明如下:

YourselfMessage

来自你本人的消息结构体。属性说明如下:

// 施工中