GameLink接口使用指南(Cocos2d-x)

概述

GameLink SDK(以下简称GameLink)是针对Cocos2d-x和Unity3D两款主流游戏引擎推出的跨平台(Windows/Mac/iOS/Android)游戏即时通讯SDK,支持基于单聊/频道(聊天室)的文字和语音短信聊天功能。本文档主要介绍GameLink Cocos2d-x(c++)接口使用。

接口

准备

开始使用GameLink前,请先注册登录管理平台创建一个应用,获取到该应用所对应的appkey。然后下载GameLink的Cocos2d-x版本并集成到工程中。

调用约定

GameLink的所有接口都必须在Cocos2d-x的UI主线程调用,同时GameLink也会确保所有异步回调在UI主线程执行。

接口使用前,请引用GameLink头文件和名空间:

#include "GameLink.h"

using namespace gamelink;

初始化

使用注册好的appkey完成GameLink的初始化:

GameLink::init("<appkey>");

该接口返回true才能继续其他接口调用。appkey作为应用唯一标识,其重要性和安全性不言而喻,我们强烈建议通过游戏服务器使用加密方式分发该参数到客户端

开启日志

默认情况下日志功能关闭,如需辅助定位问题可开启:

GameLink::enableLog(true);

回调监测

GameLink依赖Cocos2d-x的调度器(Scheduler)定时监测异步回调:

director->getScheduler()->schedule([](float tm){
    GameLink::pump();
}, this, 0.05f, false,"gamelink");

director为Cocos2d-x的导演类(CCDirector)单实例,注意pump函数的定时执行必须在整个App的运行期间都是有效的,因此这段代码不要放在一个可能随时被释放的对象中去执行。

清除缓存

初始化完成后,如有必要可以调用以下接口清除上次运行时缓存的文件:

GameLink::clearCache();

监听器

监听异步回调,需要从GLObserver类继承并重载需要监听的虚函数(以登录为例):

class YourObserver:public GLObserver
{
public:
    virtual void onLogin(const GLTarget& user,const GLError* error);
    ...
}

void YourObserver::onLogin(const GLTarget &user, const GLError *error)
{
    if(!error){
        // 登录成功
    }
}

在GLObserver的所有异步回调函数中,若包含GLError指针类型的参数,仅当该参数为空时,才表示接口调用成功;如果失败,则可以从参数中找到原因或解决方法。

实现了监听类后,还需要添加监听器到GameLink,才能接收到异步回调:

YourObserver *pObserver = new YourObserver();
GameLink::addObserver(*pObserver);

如果不再需要监听或者监听器即将被释放,则需要及时将其移除:

GameLink::removeObserver(*pObserver);

登录

传入任意非空字符串作为账号即可登录,该账号将作为整个应用内的唯一玩家标识(不超过64个字符):

GameLink::login("player1");

对应GLObserver异步回调函数(以下简称对应回调):

virtual void onLogin(const GLTarget& user,const GLError* error);

其中user为GLTarget类型,相关定义如下:

typedef enum
{
    GLTargetTypeUser,///< 玩家
    GLTargetTypeChannel,///< 频道
}GLTargetType;///< 目标类型


struct GLTarget
{
    GLTargetType type;///< 目标类型

    std::string account;///< 账号,即登录时传入的唯一字符串
    std::string avatar;///< 头像
    std::string nickname;///< 昵称
    std::string extraInfo;///< 扩展信息

    GLTarget();
    GLTarget(GLTargetType type, const char* username);
    GLTarget(GLTargetType type, const std::string& username);

    bool operator==(const GLTarget& target) const;
};

GameLink中的聊天分为两种:单聊和频道(聊天室)。可通过如下方法构造聊天对象:

GLTarget user(GLTargetTypeUser, "player1");// 构造一个玩家,player1为其账号
GLTarget channel(GLTargetTypeChannel, "channel1");// 构造一个频道, channel1为其频道号

GameLink接口调用出现的错误,通过GLError类给出,定义如下:

typedef struct
{
    GLErrorCode code;///< 错误码
    std::string detail;///< 错误原因
    std::string description;///< 更详细的错误描述或解决方法

    int line;///< 出错行号
    std::string function;///< 出错函数
    std::string filename;///< 出错文件
}GLError;

其中GLErrorCode错误码参考下表:

错误码 含义
GLErrorCodeRemoteException 服务器(远程)执行异常
GLErrorCodeNotInited 尚未初始化
GLErrorCodeNotOnline 账号不在线
GLErrorCodeInvalidArgument 传入参数错误
GLErrorCodeKicked 当前账号在其他设备登录,被强制下线
GLErrorCodeNetworkError 网络出现错误,账号暂时离线
GLErrorCodeAppSwitchedToBack App切换到后台,账号暂时离线
GLErrorCodeMicphoneAccessFailed 访问麦克风失败
GLErrorCodeMicphoneBusy 麦克风设备被占用
GLErrorCodeUploadFailure 文件上传失败
GLErrorCodeDownloadFailure 文件下载失败
GLErrorCodePlaybackError 音频播放失败
GLErrorCodeRecordDurationTooShort 录音时间过短
GLErrorCodeTransferNotInited 文件传输尚未初始化
GLErrorCodeFileNotExist 文件不存在
GLErrorCodeFileZeroBytes 文件内容为空
GLErrorCodeMessageNotFound 未能找到消息
GLErrorCodeOnlineOrLogining 已经处于登录状态或正在登录中
GLErrorCodeNotInChannel 不在频道中

注销

退出当前登录帐号:

GameLink::logout();

该接口是同步操作,执行完成可立即调用登录接口

对应回调:

virtual void onLogout(const GLError* error);

一旦某个账号登录成功,只要没有调用logout退出登录或者被踢下线,期间无论设备网络状态如何变化,只要网络恢复正常,GameLink都会自动重连服务器,并重新登录

玩家详情

调用登录接口后(无需等待登录成功),便可通过如下接口设置好玩家详细信息(昵称/头像/扩展信息):

GameLink::setProfile("<nickname>", "<avatar>", "<extra information>");

该接口无对应回调,设置的玩家详情不会存储到服务器,仅在发送消息时随消息体透传到接收者(玩家/频道)

语音转文字

GameLink内置讯飞语音识别功能,默认关闭,如需开启,可调用如下接口:

GameLink::enableVoiceRecognition(true);

该接口无对应回调,Windows和Mac平台暂不支持该功能

音频录制

登录成功后,可通过以下接口开始录制音频(最大时长30秒):

GameLink::startRecord();

对应回调:

virtual void onStartRecord(const GLError* error);

录音成功开始之后,可以通过以下接口获取录音状态:

float volume;
unsigned duration;
GameLink::getRecordingState(&volume, &duration);

volume表示录音瞬时音量大小,范围从0.0到1.0,duration为当前录制时长,单位为毫秒(ms), 该接口不会导致阻塞,可以高频调用刷新界面

停止录音(若录音达到最大时长,将自动停止):

GameLink::stopRecord();

对应回调:

virtual void onStopRecord(const std::string& file, const std::string& voiceContent, unsigned duration, const GLError* error);

file为本地音频文件名(随机UUID),voiceContent是语音转文字结果(如开启了语音识别功能),duration是本次录音时长(毫秒)

音频播放

音频文件可以通过以下接口来播放:

GameLink::playVoice(file);

file是录制或下载好的本地音频文件名(UUID)

对应回调:

virtual void onPlayStart(const std::string& file, const GLError* error);

file为接口传入的文件名

播放成功开始后,可以通过以下接口获取播放状态:

float volume;
unsigned duration;
GameLink::getPlayingState(&volume, &duration);

volume表示播放瞬时音量大小,范围从0.0到1.0,duration为当前播放进度,单位为毫秒(ms), 该接口不会导致阻塞,可以高频调用刷新界面

停止播放(播放完毕自动调用):

GameLink::stopPlay();

对应回调:

virtual void onPlayStop(const std::string& file);

file含义同上

playVoice接口有一个重载函数,用来播放音频消息:

GameLink::playVoice(message);

message为GLMessage消息对象,并且为音频消息类型

对应回调:

virtual void onPlayStart(const GLMessage &message, const GLError* error);
virtual void onPlaying(const GLMessage &message, unsigned duration);
virtual void onPlayStop(const GLMessage &message);

以上3个回调和播放文件的回调仅仅只是参数差异,这里不再做详细说明

音频上传

将音频文件上传到GameLink服务器:

GameLink::uploadVoice(file);

file是本地音频文件名(UUID)

对应回调:

virtual void onUploadVoice(const std::string& file, const std::string& url, const GLError* error);

file含义同上,url为音频文件存储在GameLink服务器的相对地址(UUID)

音频下载

从GameLink服务器下载音频到本地:

GameLink::downloadVoice(url);

url为音频文件存储在GameLink服务器的相对地址(UUID)

对应回调:

virtual void onDownloadVoice(const std::string& url, const std::string& file, const GLError* error);

url含义同上,file为下载成功后的本地文件名

downloadVoice接口有一个重载函数,用来下载消息中的音频文件:

GameLink::downloadVoice(message);

message为GLMessage消息对象,并且为音频消息类型

对应回调:

virtual void onDownloadVoice(const GLMessage& message, const GLError* error);

频道(聊天室)

GameLink频道分为两种:固定频道和临时频道。

固定频道支持获取历史聊天记录,不能从客户端创建;临时频道不支持获取历史聊天记录,但能直接从客户端创建。因此固定频道比较适合世界频道聊天场景,而临时频道更适合组队聊天场景。

固定频道的创建需要登录到管理平台才能操作,创建好之后,客户端可通过以下接口获取到固定频道列表:

GameLink::getPermanentChannels(0, 10);

上述调用将会向服务器请求第0页固定频道列表,每页数量为10个。

对应回调:

virtual void onGetPermanentChannels(unsigned pageIndex, const std::vector<GLTarget>& channels, const GLError* error);

pageIndex为调用接口时传入的页索引,channels存储了获取到的固定频道列表

频道聊天前,需要先加入频道:

GameLink::joinChannel("channel1");

等价于:

GLTarget channel(GLTargetTypeChannel, "channel1");

GameLink::joinChannel(channel);

上述接口请求加入名为channel1的频道,GameLink的频道以字符串作为唯一标识,名字相同,即为同一频道。如果该频道不存在,服务器将自动创建一个临时频道,当所有玩家都退出该频道后,会自动被服务器销毁, 聊天记录也将被清空。

对应回调:

virtual void onJoinChannel(const GLTarget& channel, const GLError* error);

离开指定频道:

GameLink::leaveChannel("channel1");

等价于:

GLTarget channel(GLTargetTypeChannel, "channel1");
GameLink::leaveChannel(channel);

因网络情况导致掉线,玩家将自动离开掉线前进入的所有频道

对应回调:

virtual void onLeaveChannel(const GLTarget& channel, const GLError* error);

获取频道当前成员列表(第0页,每页数量10个):

GLTarget channel(GLTargetTypeChannel, "channel1");
GameLink::getChannelMemberList(channel, 0, 10);

对应回调:

void onGetChannelMemberList(const GLTarget& channel, unsigned pageIndex, unsigned total, const std::vector<std::string>& memberlist, const GLError* error);

如果获取成功,total表示当前频道总人数,memberlist存储的是当前页的成员ID列表

消息接收

玩家处于在线状态时,如收到离线或即时消息(单聊/频道),会自动触发以下回调:

virtual void onReceiveMessage(const GLMessage& message);

GLMessage的相关定义如下:

typedef enum
{
    GLMessageTypeText,///< 文本消息
    GLMessageTypeVoice,///< 语音消息
    GLMessageTypeCustom,///< 自定义消息
}GLMessageType;///< 消息类型枚举

typedef enum
{
    GLMessageStatusCreated,///< 已创建
    GLMessageStatusSending,///< 发送中
    GLMessageStatusSent,///< 已发送
    GLMessageStatusSendingFailed,///< 发送失败

    GLMessageStatusReceived///< 接收到的消息
}GLMessageStatus; ///< 消息状态枚举


struct GLMessage
{
    GLMessageType type;///< 消息类型
    GLMessageStatus status;///< 消息状态

    GLTarget sender;///< 消息发送者
    GLTarget receiver;///< 消息接收者

    unsigned id;///< 消息ID,仅本地有效(不存储服务器)
    unsigned long long date;  ///< 消息时间(自1970/1/1 00:00:00经历纳秒数) 

    std::string text;///< 文本内容(语音消息识别结果)
    std::string extraText;///< 扩展文本内容

    unsigned duration;///< 语音消息时长(毫秒)
    std::string url;///< 音频文件下载地址
    std::string file;///< 本地音频文件名

  ... ///< 构造函数或其他成员函数
};

不论是发送还是接收,GLMessage对象都是由GameLink生成,因此不要自行尝试构造一个GLMessage对象。

发送消息

发送消息前,定义好消息接收者:

GLTarget receiver(GLTargetTypeUser, "player1");// player1为接收者账号

或频道(发送前需加入频道):

GLTarget receiver(GLTargetTypeChannel, "channel1");// channel1为其频道号

发送文本消息:

GameLink::sendText(receiver, "<消息文本内容>", "<消息扩展内容>");

发送自定义消息:

GameLink::sendCustomText(receiver, "<消息自定义内容>", "<消息扩展内容>");

发送语音消息:

GameLink::sendVoice(receiver, url, duration, "<消息扩展内容>", "<语音识别结果>");

url为音频文件上传后的下载地址,duration是语音时长(毫秒),如填充了语音识别结果,其内容存储在GLMessage的text字段

对应回调:

virtual void onSendMessage(const GLMessage& message, const GLError* error);

消息管理

获取和某个玩家(频道)的本地聊天消息列表:

std::vector<GLMessage> msglist = GameLink::getMessageList(target, 10);

其中target为GLTarget对象,第二个参数表示获取聊天记录里的多少条最新消息,传0表示获取全部聊天记录

清除和某个玩家(频道)的本地聊天消息列表:

GameLink::clearMessageList(target);

其中target为GLTarget对象,清除消息将同时删除对应的音频文件(如果存在的话)

从服务器拉取某个频道的历史聊天消息列表(最近10条):

GLTarget channel(GLTargetTypeChannel, "channel1");
GameLink::getHistoryMessageList(channel, 10);

对应回调:

void onGetHistoryMessageList(const GLTarget& target, unsigned count, const GLError* error);

如果获取成功,count返回实际获取到的历史消息条数,可通过getMessageList获取到从服务器返回的历史消息

返回顶部