PLUG COCOS-2DX 应用指南

应用指南

1. 项目设置

将所下载示例项目中包含的sample/Classes/plugincafe文件夹复制到游戏项目中。
根据相应的操作系统，选择并添加正确的PLUG SDK项目。
- Android:将sample/proj.android-studio/app/libs文件夹下的PLUG SDK项目作为库添加至游戏项目。
- iOS:将lib/iOS文件夹下的PLUG SDK项目添加至游戏项目。

2. 初始化

根据PLUG SDK支持的语言，按照如下方法将PLUG SDK初始化。

2.1 PLUG SDK初始化（仅支持韩语 - NAVER Cafe）

将仅支持韩语的PLUG SDK初始化时，设置如下初始化信息。

在“使用NAVER ID登录开发人员中心”注册应用程序后获得的客户端ID（ClientId）和客户端Secret（ClientSecret）。
在NAVER Cafe创建Cafe后获得的Cafe ID。

cafe::CafeSdk::init("U5ZHoj_OStOHOJ8mec_s", "piPHPA9i4E", 28334359 );

2.2 PLUG SDK初始化（仅支持外语）

将仅支持外语的PLUG SDK初始化时，设置如下初始化信息。

consumerKey: 创建社区后获得的Consumer Key。
consumerSecretKey: 创建社区后获得的Consumer Secret Key。
cummunityNo: 创建社区后获得的Cummunity No。
loungeNo: 创建lounge后获得的Lounge No。

cafe::CafeSdk::initGlobal("PLUGTESTKEY", "PLUGTESTSECRET", 1, 58);

3. 启动PLUG SDK

完成初始化后，运行PLUG SDK。

3.1 startHome()方法

startHome()是启动PLUG SDK的方法。

cafe::CafeSdk::startHome();

Android Studio示例项目

在Android Studio中打开sample/proj.android-studio文件夹中的项目。
导入项目。
确认PLUG在应用程序中是否正常运行。

iOS示例项目

在XCode中打开sample/proj.ios_mac文件夹中的项目
导入项目。
确认PLUG在应用程序中是否正常运行。

支持国外社区和韩国国内NAVERCafe的PLUG初始化

对于同时支持国外社区和韩国国内NAVER Cafe的PLUG，需要同时完成为支持国外社区的初始化设置和为支持韩国国内NAVER Cafe的初始化设置。

PLUG启动与退出

以特定标签被选择的状态启动或退出PLUG。

startHome()方法

以主页标签被选择的状态启动PLUG。

static void startHome()

下面是实现startHome()方法的示例。

   /**
   * 以主页标签启动
   */
  cafe::CafeSdk::startHome();

横屏模式及竖屏模式

PLUG同时支持横屏模式和竖屏模式。

Android

Android环境下，无需另外设置，系统将根据界面的横竖状态自动应用横屏或竖屏模式。

iOS

iOS环境下，利用setOrientationIsLandscape: 方法应用横屏或竖屏模式。

下面是以横屏模式运行PLUG的示例。

//缺省值为YES
//横屏模式
[[NCSDKManager getSharedInstance] setOrientationIsLandscape:YES];

下面是以竖屏模式运行PLUG的示例。

// 竖屏模式
[[NCSDKManager getSharedInstance] setOrientationIsLandscape:NO];

透明度调节

如果利用PLUG界面左上方的透明度调节滑块调节透明度，则可以同时使用游戏和Cafe服务。

透明度

说明

Alpha值100%

向PLUG报告点击事件

Alpha值100%以下

向游戏报告点击事件

Android

在Android环境下，利用setTransparentable()方法设置是否使用透明度调节滑块。

public static void setTransparentable(Activity activity, boolean isTransparentable)

将isTransparentable参数值设置为true时，可以使用透明度调节滑块（缺省值：true）。

下面是使用透明度调节滑块的示例。

  /**
   * 设置是否使用透明度调节滑块
   *
   * @param isTransparentable 确定是否能使用透明度调节功能的boolean值
   */
  Glink.setTransparentable(activity, true)

iOS

在iOS环境下是否使用透明度调节滑块，用disableTransparentSlider: 方法设置。

(void)disableTransparentSlider:(BOOL)disable;

将disable参数值设置为YES时，可以使用透明度调节滑块（缺省值：YES）。

下面是使用透明度调节滑块的示例。

/*
 取消透明度调节功能
 缺省值：YES
 */
//使用透明度调节功能
[[NCSDKManager getSharedInstance] disableTransparentSlider:YES];

下面是不使用透明度调节滑块的示例。

//取消透明度功能
[[NCSDKManager getSharedInstance] disableTransparentSlider:NO];

微件

微件是点击PLUG收起按钮时自动显示在界面中的构成要素。利用微件可在游戏内的任何环境下使用PLUG。

微件显示

点击PLUG的收起按钮时，利用ShowWidgetWhenUnloadSdk()方法设置是否显示微件。

static void showWidgetWhenUnloadSdk(bool show)

如果将show参数值设置为true，收起PLUG窗口时显示微件（缺省值：true）。

下面是显示微件的示例。

  /**
   * 决定PLUG窗口收起时是否显示微件
   *
   * @param show 确定是否显示微件的Boolean值
   */
  cafe::CafeSdk::showWidgetWhenUnloadSdk(true);

关闭微件

如果要关闭微件，使用stopWidget()方法。.

static void stopWidget()

下面是强制关闭微件的示例。

  /**
   * 关闭微件
   */
  cafe::CafeSdk::stopWidget();

微件默认位置设置

微件在第一次运行时，显示在界面左侧中央位置。如果要设置微件第一次运行时的默认显示位置，使用setWidgetStartPosition()方法。

但如果是在用户移动微件位置后重新运行的情况，则显示在用户移动后的最终位置。

static void setWidgetStartPosition(bool isLeft, int heightPercentage);

下面是将微件默认位置设置在界面右侧距上部20%处的示例。

  /**
   * isLeft:true时显示在左侧，false时显示在右侧。
   * heightPercentage:竖直方向的位置可使用百分数指定。
   */
  cafe::CafeSdk::setWidgetStartPosition(false, 20);

截屏

点击微件的截屏按钮可以截取游戏画面。

截屏按钮

点击截屏按钮截屏的功能，通过在onCafeSdkWidgetScreenshotClick()方法中注册微件截屏按钮的点击监听器（onCafeSdkWidgetScreenshotClick）来实现。

virtual void onCafeSdkWidgetScreenshotClick()

下面是实现微件截屏按钮点击监听器的示例。

  /**
   * 注册实现监听器的类
   */
bool HelloWorld::init()
{
...
    cafe::CafeSdk::setCafeListener(this);
...    
    return true;
}

  /**
   * 设置微件截屏按钮点击监听器
   */
void HelloWorld::onCafeSdkWidgetScreenshotClick() {
    CCSize screenSize = Director::getInstance()->getWinSize();
    RenderTexture* texture = RenderTexture::create(screenSize.width,
            screenSize.height);
    texture->setPosition(Vec2(screenSize.width / 2, screenSize.height / 2));

    texture->begin();
    Director::getInstance()->getRunningScene()->visit();
    texture->end();

    std::string fileName = "captured_image.png";
    if (texture->saveToFile(fileName, Image::Format::PNG)) {
        std::string imageUri = FileUtils::getInstance()->getWritablePath()
                + fileName;
        cafe::CafeSdk::startImageWrite(imageUri);
    }
}

截屏功能使用设置

s使用setUseScreenshot()方法设置是否使用截屏功能。

static void setUseScreenShot(bool use);

将use参数值设置为true时，微件显示截屏按钮（缺省值：true）。

下面是使用截屏功能的示例。

  /**
   * 使用截屏功能
   */
  cafe::CafeSdk::setUseScreenShot(true);

视频录制

在微件界面点击视频录制按钮可录制游戏画面。

点击视频录制按钮录制游戏画面的功能，通过在onCafeSdkOnRecordFinished()方法中注册微件视频录制按钮监听器（onCafeSdkOnRecordFinished）来实现。

virtual void onCafeSdkOnRecordFinished(const std::string& fileUrl)

下面是实现视频录制按钮点击监听器的示例。

  /**
   * 注册实现监听器的类
   */
bool HelloWorld::init()
{
...
    cafe::CafeSdk::setCafeListener(this);
...    
    return true;
}

  /**
   * 设置微件视频录制按钮点击监听器
   */
void HelloWorld::onCafeSdkOnRecordFinished(const std::string& fileUrl) {
    cafe::CafeSdk::startVideoWrite(fileUrl);
}

视频录制

点击录制视频按钮可在游戏过程中录制游戏画面。

视频录制功能支持Android 5.0以上设备。
视频录制功能支持iOS 9.0以上设备。

使用微件视频录制功能

点击微件视频录制按钮可在游戏过程中录制游戏画面。

视频录制功能使用设置

使用setUseVideoRecord()方法设置是否使用视频录制功能。

static void setUseVideoRecord(bool use)

将use参数值设置为true时，微件显示视频录制按钮（缺省值：false）。

低于Android 5.0或iOS 9.0版本的设备，即使将use参数值设置为true，也不会在微件上显示视频录制按钮。

下面是使用视频录制功能的示例。

  /**
   * 决定是否使用视频录制功能
   *
   * @param use 确定是否使用视频录制功能的boolean值
   */
  cafe::CafeSdk::setUseVideoRecord(true)

录制结束回调监听器

视频录制结束后，需要处理的内容通过注册监听器onCafeSdkOnRecordFinished来实现。

virtual void onCafeSdkOnRecordFinished(const std::string& fileUrl)

下面是实现录制结束监听器的示例。

//注册录制结束监听器
cafe::CafeSdk::setCafeListener(this);

   /**
   * 视频录制结束后调用
   *
   * @param uri 所录制视频文件的路径URI（iOS中没有URI）
   */
void HelloWorld::onCafeSdkOnRecordFinished(const std::string& fileUrl) {
    cafe::CafeSdk::startVideoWrite(-1, "", "", fileUrl);
}

使用游戏视频录制功能

游戏开发商可通过设置视频录制按钮支持游戏画面的录制。

开始录制视频

如果要开始录制视频，使用startRecord()方法。

在低于Android 5.0或iOS 9.0版本的设备上无法录制视频。

static void startRecord();

下面是开始录制视频的示例。

  /**
   * 开始录制视频
   *
   */
  cafe::Record::startRecord();

结束视频录制

如果要结束录制视频，使用stopRecord()方法。

static void stopRecord();

下面是结束视频录制的示例。

  /**
   * 结束视频录制
   *
   */
  cafe::Record::stopRecord();

录制结束回调监听器

视频录制结束后，需要处理的内容通过在setRecordListener()方法中注册录制结束监听器（onSDKRecordFinish）来实现。

static void setRecordListener(RecordListener* listener);

下面是实现录制结束回调监听器的示例。

    //注册监听器
    cafe::Record::init();
    cafe::Record::setRecordListener(this);


   /**
   * 视频录制结束后调用
   *
   * @param uri 所录制视频文件的路径URI（iOS中没有URI）
   */
void HelloWorld::onSDKRecordFinish(const std::string& uri) {
    cafe::CafeSdk::startVideoWrite(uri);
}

App Scheme处理

在游戏中，点击PLUG主页显示的横幅图片，即可移动至App Scheme运行游戏功能。

用于引导前往App Scheme的横幅图片在Cafe管理菜单下添加。

Android

Android环境下存在可前往App Scheme的横幅图片时，如果按照下面的方法设置onCafeSdkClickAppSchemeBanner监听器，则可以实现发生点击事件时处理App Scheme的功能。

virtual void onCafeSdkClickAppSchemeBanner(const std::string& appScheme)

下面是实现App Scheme处理的监听器示例。

...
// 设置回调
cafe::CafeSdk::setCafeListener(this);
...

// 设置App Scheme点击监听器
void HelloWorld::onCafeSdkClickAppSchemeBanner(const std::string& appScheme) {
    cafe::CafeSdk::showToast(appScheme);
}

iOS

在iOS环境下，点击前往App Scheme的横幅图片，即可运行openURL：方法来处理App Scheme的功能，按照如下示例设置AppDelegate。

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
...
/// 利用AppDelegate处理添加至管理菜单的Scheme
//ex : gLinkSample://test
    if ([[url scheme] isEqualToString:@"gLinkSample"]) {
        if ([[url host] isEqualToString:@"test"]) {
            //todo
        }
    }
...
}

回调监听器

PLUG中发生的事件通过注册回调监听器来处理。

注册回调监听器

利用setCafeListener()方法注册用于处理PLUG发生事件的回调监听器。

static void setCafeListener(CafeListener* listener)

下面是注册回调监听器的示例。

   // HelloWorld.cpp
void HelloWorld::init() {
    ...
    cafe::CafeSdk::setCafeListener(this);
    ...
}

启动PLUG监听器

onCafeSdkStarted是处理PLUG启动时所发生事件的回调监听器。

virtual void onCafeSdkStarted()

下面是启动实现PLUG监听器的示例。

   // 设置启动PLUG监听器
void HelloWorld::onCafeSdkStarted() {
    cafe::CafeSdk::showToast("onCafeSdkStarted");
}

退出PLUG监听器

onCafeSdkStopped是处理退出PLUG时所发生事件的回调监听器。

virtual void onCafeSdkStopped()

下面是实现退出PLUG监听器的示例。

   // 设置退出PLUG监听器
void HelloWorld::onCafeSdkStopped() {
    cafe::CafeSdk::showToast("onCafeSdkStopped");
}

App Scheme监听器

onCafeSdkClickAppSchemeBanner是在Android环境下，处理游戏用户点击前往App Scheme的横幅图片时所发生事件的回调监听器。

virtual void onCafeSdkClickAppSchemeBanner(
            const std::string& appScheme)

下面是实现App Scheme监听器的示例。

   // 设置App Scheme监听器
void HelloWorld::onCafeSdkClickAppSchemeBanner(const std::string& appScheme) {
    cafe::CafeSdk::showToast(appScheme);
}

Cafe 注册监听器

onCafeSdkJoined是处理游戏用户通过PLUG注册Cafe时所发生事件的回调监听器。

virtual void onCafeSdkJoined()

下面是实现Cafe注册监听器的示例。

   // 设置Cafe注册监听器
void HelloWorld::onCafeSdkJoined() {
    cafe::CafeSdk::showToast("onCafeSdkJoined");
}

发帖监听器

onCafeSdkPostedArticle是处理用户在PLUG发帖时所发生事件的回调监听器。

virtual void onCafeSdkPostedArticle(int menuId, int imageCount, int videoCount)

下面是实现发帖监听器的示例。

   /** 设置发帖监听器
     * @param menuId 发帖的menuId
     * @param imageCount 同附图片文件的数量
     * @param videoCount 同附视频文件的数量
     **/
void HelloWorld::onCafeSdkPostedArticle(int menuId, int imageCount, int videoCount) {
    cafe::CafeSdk::showToast("onCafeSdkPostedArticle " + StringUtils::format("%d, %d, %d", menuId, imageCount, videoCount));
}

评论发表监听器

onCafeSdkPostedComment是处理用户在PLUG发表评论时所发生事件的回调监听器。

virtual void onCafeSdkPostedComment(int articleId)

下面是实现评论发表监听器的示例。

   // 设置评论发表监听器
void HelloWorld::onCafeSdkPostedComment(int articleId) {
    cafe::CafeSdk::showToast("onCafeSdkPostedComment " + StringUtils::format("%d", articleId));
}

投票结束监听器

onCafeSdkDidVote是处理用户在PLUG参与发起投票的贴文投票活动时所发生事件的回调监听器。

virtual void onCafeSdkDidVote(int articleId)

下面是实现投票结束监听器的示例。.

   // 设置投票结束监听器
void HelloWorld::onCafeSdkDidVote(int articleId) {
    cafe::CafeSdk::showToast("onCafeSdkDidVote " + StringUtils::format("%d", articleId));
}

截屏按钮点击监听器

onCafeSdkWidgetScreenshotClick是处理用户点击微件上截屏按钮时所发生事件的回调监听器。关于截屏按钮的详细内容，请参考“微件”部分。

virtual void onCafeSdkWidgetScreenshotClick()

下面是实现截屏按钮点击监听器的示例。只有通过回调监听器设置截屏功能，才能在点击截屏按钮时进行截屏。


  /**
   * 设置微件截屏按钮点击监听器
   */
void HelloWorld::onCafeSdkWidgetScreenshotClick() {
    CCSize screenSize = Director::getInstance()->getWinSize();
    RenderTexture* texture = RenderTexture::create(screenSize.width,
            screenSize.height);
    texture->setPosition(Vec2(screenSize.width / 2, screenSize.height / 2));

    texture->begin();
    Director::getInstance()->getRunningScene()->visit();
    texture->end();

    std::string fileName = "captured_image.png";
    if (texture->saveToFile(fileName, Image::Format::PNG)) {
        std::string imageUri = FileUtils::getInstance()->getWritablePath()
                + fileName;
        cafe::CafeSdk::startImageWrite(-1, "", "", imageUri);
    }
}

录制结束监听器

onCafeSdkOnRecordFinished是处理PULG视频录制结束时所发生事件的回调监听器。

virtual void onCafeSdkOnRecordFinished(const std::string& fileUrl)

下面是实现录制结束监听器的示例。

  /** 设置录制结束监听器
   * 决定是否使用视频录制功能
   *
   * @param uri 所录制视频文件的路径URI
   */
void HelloWorld::onCafeSdkOnRecordFinished(const std::string& fileUrl) {
    cafe::CafeSdk::startVideoWrite(-1, "", "", fileUrl);
}

游戏ID绑定

PLUG支持绑定用户的游戏ID和CafeID来进行管理。绑定后的游戏ID和Cafe ID目录可在Cafe的管理菜单下确认。

如果要绑定游戏ID和Cafe ID，使用syncGameUserId()方法。

static void syncGameUserId(std::string gameUserId)

下面是绑定游戏ID和Cafe ID的示例。

  /**
   * 绑定游戏ID和Cafe ID
   *
   * @param gameUserId 游戏ID
   */
  cafe::CafeSdk::syncGameUserId("usergameid");

主题颜色变更

可变更PLUG的主题颜色。

如果要更改主题颜色，使用setThemeColor()方法。

/** 
* themeColorCSSString参数的缺省值为 ‘#00c73c’
* tabBackgroundColorCSSString参数的缺省值为‘#44484e’
* tabBackgroundColorCSSString参数建议使用缺省值
**/

void cafe::CafeSdk::setThemeColor(std::string themeColorCSSString, std::string tabBackgroundColorCSSString)

themeColorCSString: 主题默认使用的颜色（缺省值：#00c73c）
tabBackgroundColorCSSString: 标签菜单的背景颜色（缺省值：#44484e）建议使用缺省值。

注意 CSS颜色值内不得输入alpha值。

正确示例：#ff9800
错误示例：#e2ff9800

下面是更改主题颜色的示例。

cafe::CafeSdk::setThemeColor("#00c73c", "#44484e");

资源图片变更

PLUG支持更改包含于NAVER Cafe PLUG库中的资源图片。

Android

在Android环境下，可按照如下方式更改包含于NAVER Cafe PLUG库中的资源图片。

解压NAVER Cafe PLUG 库文件（.aar文件）。
将解压后文件夹下/res/drawable-xhdpi文件夹中的图片更改为目标图片。
将解压后的文件夹重新压缩为库文件（.aar文件）
应用新压缩的NAVER Cafe PLUG库并导入项目。

주의 注意更改图片时，图片大小须和原图片大小一致。

iOS

在iOS环境下，可按照如下方式更改包含于NAVER Cafe PLUG库中的资源图片。

将NaverCafeSDK.bundle压缩包中的图片更改为目标图片。
将修改后的压缩包应用至NAVER Cafe PLUG库中后导入项目。

注意更改图片时，图片大小须和原图片大小一致。

PreviousPLUG UNREAL应用指南 NextPLUG ANDROID 应用指南

Last updated 4 years ago