‹ Google Play Games Services Doc Home

Google Play Games Services 集成指南

For the Javascript version of cocos2d-x v3.x - (all other versions)

安装

用如下命令来集成 SDKBOX IAP 插件,请确保您可以正常执行的 SDKBOX 安装器.

$ sdkbox import gpg

安装后

Android

修改 AndroidManifest.xml

在你的 AndroidManifest.xml 中添加如下 meta-data.

<meta-data android:name="com.google.android.gms.games.APP_ID"
    android:value="@string/google_app_id" />

修改 string.xml

添加如下文字到 proj.android/res/values/string.xml

<string name="google_app_id">777734739048</string>

请一定要把 google_app_id 对应的值修改为你自己的 App Id.

iOS

修改 proj.ios_mac/ios/AppController.mm

AppController.mm 中添加如下代码:

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary *)options {
    return [[GIDSignIn sharedInstance] handleURL:url
                               sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]
                                      annotation:options[UIApplicationOpenURLOptionsAnnotationKey]];
}

设置自己的 Google Play Signin Listener (可选)

设置 GPG(Google Play Game Services) SignIn 的回调

这不是必选的,SDKBox GPG 已经在内部设置了对应的 Delegate, 当你在外面自己手动设置 GIDSignInUIDelegate 时,内部的就会被忽略

在外面自己手动设置 GIDSignInUIDelegate , 如下步骤:

修改 proj.ios_mac/ios/RootViewController.hRootviewController 实现 GIDSignInUIDelegate:

#import <GoogleSignIn/GoogleSignIn.h>

// 在 RootViewController 类的定义中加上:
@interface RootViewController : UIViewController<GIDSignInUIDelegate>

设置 Google SignIn Listener

修改 proj.ios_mac/ios/AppController.mm

添加如下代码:

(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions

在 return 前添加如下代码:

    // _viewController could also be named
    //  viewController, depending of the project type.
    [GIDSignIn sharedInstance].uiDelegate = _viewController;

添加 URL types

添加如下 URL types 到你的工程中, 路径为 your project > Info > URL Types

更多资料

官方文档中查看更多的相关信息

重点注意事项

如果您升级到了 Xcode7, 则需要以下额外步骤来确保插件工作正常:

禁用应用程序安全传输策略

添加以下项到 plist:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

添加后的文件内容看起来就像这样:

禁止 Bitcode 支持

您必须禁止 Bitcode 的支持,否则将会编译失败。

游戏全屏配置

如果您的游戏不同时支持横竖屏,则必须在 Xcode 中选中 Requires full screen,否则将不会通过 Apple 的审核。

canOpenURL 白名单

取决于您使用哪些插件。需要在 info.plistLSApplicationQueriesSchemes 下添加名单。

关于 Creator 工程

Creator 导出工程会修改工程的配置, 这可能会影响 SDKBox 对工程的配置修改. 所以可以有以下做法(任选其一):

  1. 保存导出工程中的修改, 对于 SDKBox 来说可能有这些文件(mk, gradle, gradle.properties, AppDelegate.cpp, ...), 导出后再恢复对应该文件
  2. 在每一次 Creator 导出工程后, 重新 import 插件.

推荐第一种, 但是第一种的麻烦点在于, 对于第一次(或很久没接触的人)可能会有露掉某个文件 第二种, 很方便, 它的麻烦点在于, 如果你对工程有自己的修改, SDKBox 的重新 import 不能帮你恢复.

用法

前期准备

你必须在Google Play Developer console 创建一个自己的 app , 同时请确保所有的服务都是 enable 状态, 对应的配置也是配置正确的.

提示: Google Play Game Services 默认使用 release keystore, 如果你想用 debug 模式来测试, 看下这个方法

注册 Javascript 功能

你需要在使用 Google Play Games JS 前,先注册到 cocos2d-x.

这样做: * 在 ./frameworks/runtime-src/Classes/AppDelegate.cpp 中包含如下头文件:

#include "PluginGPGJS.hpp"
#include "PluginGPGJSHelper.h"
    sc->addRegisterCallback(register_all_PluginGPGJS);
    sc->addRegisterCallback(register_all_PluginGPGJS_helper);

初始化 Google Play Games

Google Play 是通过 gpg.Builder 这个类来初始化的.

这一个认证相关的代码,你可以直接拷贝粘贴来运行它:


//Initialization
var config = new gpg.PlatformConfiguration();
config.SetClientID('777734739048-cdkbeieil19d6pfkavddrri5o19gk4ni.apps.googleusercontent.com');

new gpg.GameServices.Builder()
            .SetOnAuthActionStarted( function( result ) {
                // Auth started callback
            })
            .SetOnAuthActionFinished( function( result ) {
                // Auth finished callback
            })
            .SetLogging( gpg.LogLevel.INFO )    // Set Logging level
            .EnableSnapshots()                  // Enable Snapshot (Saved Game) functionailty
            .Create( config, function( game_services ) {
                // 8
            } );

下面一步一步来操作.

初始化

创建一个 gpg.PlatformConfiguration 类. 传入 client id, 这个只在 ios 上是需要的.

下一步就是创建一个 GameServices 类,它提供了访问 Googol Play Game 服务的接口.

Authorization 回调

GPG的 authentication 有两个回调 AuthActionStartedAuthActionFinished

Auth 开始

//result.AuthOperation indicates if user wants sign in or sign out
.SetOnAuthActionStarted(
    function( result ) {
        cc.log('on auth action started: ' + result.AuthOperation);
    })

Auth 结束

.SetOnAuthActionFinished(
    function( result ) {
        cc.log('on auth action finished: ' + result.AuthOperation + ' ' + result.AuthStatus);
    })

设置 Logging 等级

设置 Logging 等级是可选的步骤. 这是唯一的一个地方可以控制 Logging 等级的地方.

启用 Saved Game

如果你想保存游戏数据到云服务器中, 就在初始化时设置它.

创建

到这一步,authentication 之前的代码就差不多了. 然后 Create 函数就是真正的使用之前的设置去 authenticated, 通知是否成功,返回可访问的 GPG 类 GPG的交互都通过 gpg.GameServices 类来操作. 如果一切成功的话, 这个类会在 Create 的回调中返回。

Authorization

所有的 Google Play Game 服务都需要用户先登录. 所以在 GPG 初始化后, 你应该让用户登录

    game_services.StartAuthorizationUI();

Achievements

成就是一个让用户有参与感很好的方法.你可以用游戏中的成就来鼓励用户去完成一些,平常他们不会去完成任务, 或让玩家去做与你的游戏本身风格不同的尝试.同时也是让玩家之间比较各自的游戏进度会是一个很容易的事.

比如你可以解锁 gpg.GameServices.Achievements.Unlock, 增加 gpg.GameServices.Achievements.Increment, 提示 gpg.GameServices.Achievements.Reveal 成就.

更多信息请参见: Achievements 文档

Leaderboards

游戏排行榜是一个有趣的方式来驱动你的玩家之间竞争, 游戏中资深的玩家会想在公共榜的榜首, 更多的普通玩家就会想与他们的朋友之间比较。

比如,有取排行榜的接口 gpg.GameServices.Leaderboards.Fetch, 有以页的形式取玩家分数的接口 gpg.GameServices.Leaderboards.FetchScorePage, 等.

更多信息请参见: Leaderboards 文档

Saved Games

Saved Games服务给你一个方便的方式来保存玩家的比赛进展到谷歌的服务器。你的游戏可以检索已保存的游戏数据允许玩家从任何设备在他们最后的保存点继续游戏。Saved Games服务可以同步一个玩家的游戏数据跨多个设备。

更多信息请参见: Saved Games 文档

Real-time multiplayer

您的游戏可以使用Google Play游戏服务中的实时多人API,在单个游戏会话中将多个玩家连接在一起,并在连接的玩家之间传输数据消息。使用实时多人API可以帮助简化您的游戏开发工作,因为API代表您处理以下任务:

更多信息请参见: Real-time Multiplayer 文档

Turn-based multiplayer

在基于回合的多人游戏中,在多个玩家之间传递共享一个状态,并且在一个回合中只有一个玩家具有修改共享状态的许可。 玩家根据由游戏确定的游戏顺序异步轮流。 您的游戏可以使用Google Play游戏服务提供的回合制多人API来管理以下任务:

更多信息请参见: Turn-based Multiplayer 文档

Player Statistics

获取和设置各种玩家相关数据。例如,取得当前登录的玩家的信息 “gpg.GameServices.Players.FetchSelf”,或由id来匹配的玩家信息 “gpg.GameServices.Players.Fetch”。此外,玩家统计可以获得一些有趣的信息,例如玩家的平均会话长度,上次玩的天数或他在游戏上购买的数量。 更多信息请参见: Player Stats 文档

Events and Quests

Google Play Game 事件服务允许你收集玩家在游戏中的数据并存储在Google的服务器中分析。 你可以灵活地定义你的游戏应该收集什么玩家数据; 这可能包括以下指标:

您可以根据事件数据的反馈来决定如何改进您的游戏。 例如,您可以调整游戏中某些级别的难度级别,玩家发现太难以完成。

例如,你可以接受一个任务gpg.GameServices.Quests.Accept或在一个任务上声明里程碑gpg.GameServices.Quests.AcceptMilestone

更多信息请参见: Events and Quests 文档

Nearby Connections

Nearby Connections可以让你的游戏有本地多人和屏幕投射功能. 更多信息请参见: Nearby 文档

API 文档

所有的 javascript 代码都有注释,并且 Javascript IDE 比如 IntelliJ, Webstorm, Visual Studio Code, 等中都有提示.

Google Play Games JS 在线文档

手动集成

如果用 SDKBox Installer 安装失败了, 可以用手动的形式来集成. 如果用 SDKBox Installer 安装成功了,那么不用再手动来集成了.

这些步骤放在文档的最后,因为基本上你很少时候会有需要到他们. 当你要手动集成时,请在完成后,再看一个手动集成以上的这些步骤.

iOS手动集成步骤

GooglePlay 包中 plugins/ios 目录下的如下 frameworks 拖到你的 Xcode 工程中, 请确保 Copy items if needed 是选中状态:

sdkbox.framework

PluginGPG.framework

GoogleAppUtilities.framework

GoogleAuthUtilities.framework

GoogleNetworkingUtilities.framework

GoogleOpenSource.framework

GooglePlus.bundle

GooglePlus.framework

GoogleSignIn.bundle

GoogleSignIn.framework

GoogleSymbolUtilities.framework

GoogleUtilities.framework

gpg.bundle

gpg.framework

以上 framwork 是依赖于如下 framework 的,如果你的工程中还没有如下 framework , 添加上:

AddressBook.framework

AssetsLibrary.framework

CoreData.framework

CoreLocation.framework

CoreMotion.framework

CoreTelephony.framework

CoreText.framework

Foundation.framework

MediaPlayer.framework

QuartzCore.framework

SafariServices

Security.framework

StoreKit

Security.framework

SystemConfiguration.framework

libc++.dylib

libz.dylib

在工程中添加如下 linker flag ,工程路径为 Target -> Build Settings -> Linking -> Other Linker Flags:

-ObjC

代码修改

修改 proj.ios_mac/ios/AppController.mm

AppController.mm 中添加如下代码:

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary *)options {
    return [[GIDSignIn sharedInstance] handleURL:url
                               sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]
                                      annotation:options[UIApplicationOpenURLOptionsAnnotationKey]];
}

设置自己的 Google Play Signin Listener (可选)

设置 GPG(Google Play Game Services) SignIn 的回调 这不是必选的,SDKBox GPG 已经在内部设置了对应的 Delegate, 当你在外面自己手动设置 GIDSignInUIDelegate 时,内部的就会被忽略

在外面自己手动设置 GIDSignInUIDelegate , 如下步骤:

修改 proj.ios_mac/ios/RootViewController.hRootviewController 实现 GIDSignInUIDelegate:

#import <GoogleSignIn/GoogleSignIn.h>

// 在 RootViewController 类的定义中加上:
@interface RootViewController : UIViewController<GIDSignInUIDelegate>

设置 Google SignIn Listener

修改 proj.ios_mac/ios/AppController.mm

添加如下代码:

(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions

在 return 前添加如下代码:

    // _viewController could also be named
    //  viewController, depending of the project type.
    [GIDSignIn sharedInstance].uiDelegate = _viewController;

添加 URL types

添加如下 URL types 到你的工程中, 路径位置 your project > Info > URL Types

更多信息

官方文档上有更多信息

plugin/jsbindings 文件夹中所有的头文件和源文件都拷贝到你的工程的 Classes 文件夹中.

把刚刚拷贝的文件拖动到 Xcode 中或使用 File -> Add files to... 来添加.

Android 手动集成

SDKBox 支持三种 Android 工程, command-line, eclipseAndroid Studio.

拷贝文件

把安装包中的 plugin/android/libs 目录下的如下 jar 文件拷贝到你的工程中的 /libs 目录下.

拷贝 jni 库

plugin/android/jni/ 拷贝并覆盖 <your_project_root>/jni/ 目录.

修改 AndroidManifest.xml

添加如下 meta-data :

<meta-data android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />
<meta-data android:name="com.google.android.gms.games.APP_ID"
    android:value="@string/google_app_id" />

请确保添加如下 <string name="google_app_id">777734739048</string>res/values/string.xml 中. 一定要用你自己的 google app id 来代替.

修改 Android.mk

gpg 拷贝到 proj.andrid/jni 目录下

添加如下内容到你的 android.mk 文件中

添加头文件目录

LOCAL_C_INCLUDES += ./gpg/include/

添加静态库

添加静态库到 LOCAL_WHOLE_STATIC_LIBRARIES:

LOCAL_WHOLE_STATIC_LIBRARIES += gpg-1
LOCAL_WHOLE_STATIC_LIBRARIES += PluginGPG
LOCAL_WHOLE_STATIC_LIBRARIES += sdkbox

import-module 语句之前添加如下调用:

$(call import-add-path,$(LOCAL_PATH))

import-module 语句之后添加如下语句:

$(call import-module, ./gpg)
$(call import-module, ./sdkbox)
$(call import-module, ./plugingpg)

注意: 如果你使用的是预编译版本, 请一定要确保以上语句是在 $(call import-module,./prebuilt-mk) 之前.

修改 Application.mk (只适用于 Cocos2d-x v3.0 to v3.2)

查看 <project_root>/jni/Application.mk 中的 APP_STL 是否定义正确. 如果 Application.mk 包含了 APP_STL := c++_static 语句, 那么请改为:

APP_STL := gnustl_static

plugin/jsbindings 文件夹中所有的头文件和源文件都拷贝到你的工程的 Classes 文件夹中.

把你刚刚拷贝的 .cpp 文件添加到 Android.mk 文件的的 LOCAL_SRC_FILES 项.比如

LOCAL_SRC_FILES := hellocpp/main.cpp \
                  ../../Classes/AppDelegate.cpp \
                  ../../Classes/HelloWorldScene.cpp \
                                    ../../Classes/NewSourceFile.cpp

修改 AppActivity.java

插件版本 >= 2.4.0.3

  1. 找到 AppActivity.java 文件
find . -name "AppActivity.java"
  1. extends Cocos2dxActivity 替换为 extends com.sdkbox.plugin.SDKBoxActivity

以下是 AppActivity.java 不同版本的引擎所在的目录:

cpp
  - proj.android/src/org/cocos2dx/cpp/AppActivity.java
  - proj.android-studio/app/src/org/cocos2dx/cpp/AppActivity.java
  - proj.android/app/src/org/cocos2dx/cpp/AppActivity.java ( from cocos2d-x 3.17)

lua
  - frameworks/runtime-src/proj.android/src/org/cocos2dx/lua/AppActivity.java
  - frameworks/runtime-src/proj.android-studio/app/src/org/cocos2dx/lua/AppActivity.java
  - frameworks/runtime-src/proj.android/app/src/org/cocos2dx/lua/AppActivity.java (from cocos2d-x 3.17)

js
  - frameworks/runtime-src/proj.android/src/org/cocos2dx/javascript/AppActivity.java
  - frameworks/runtime-src/proj.android/app/src/org/cocos2dx/javascript/AppActivity.java ( from cocos2d-x 3.17)

插件版本 < 2.4.0.3

Note: 当你使用 cocos2d-x 源代码时,不同的版本中 Cocos2dxActivity.java 文件的位置也不同。一个确定该文件位置的方法是查看 proj.android/project.properties 。比如:

android.library.reference.1=../../cocos2d-x/cocos/platform/android/java

在这个例子中, Cocos2dxActivity.java 文件应该在如下位置:

../../cocos2d-x/cocos/platform/android/java/src/org/cocos2dx/lib/Cocos2dxActivity.java
import android.content.Intent;
import com.sdkbox.plugin.SDKBox;
onLoadNativeLibraries();
SDKBox.init(this);
    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
          if(!SDKBox.onActivityResult(requestCode, resultCode, data)) {
            super.onActivityResult(requestCode, resultCode, data);
          }
    }
    @Override
    protected void onStart() {
          super.onStart();
          SDKBox.onStart();
    }
    @Override
    protected void onStop() {
          super.onStop();
          SDKBox.onStop();
    }
    @Override
    protected void onResume() {
          super.onResume();
          SDKBox.onResume();
    }
    @Override
    protected void onPause() {
          super.onPause();
          SDKBox.onPause();
    }
    @Override
    public void onBackPressed() {
          if(!SDKBox.onBackPressed()) {
            super.onBackPressed();
          }
    }

修改 project.properties

添加 Google Play Services Android 库引用, 其路径因你的配置而有所不同. 并且 Google Play Services 不是默认下载的, 您需要打开 sdk installer , 选择 extras->google play services 下载并安装。例子:

android.library.reference.1=
../android/sdk.latest/extras/google/google_play_services/libproject/
google-play-services_lib

注意: 如果已经存在 android.library.reference.1, 您可以递增数字, 例如 android.library.reference.2, 等等.

Proguard (optional)

proguard.config=${sdk.dir}/tools/proguard/proguard-android.txt:proguard-project.txt
# cocos2d-x
-keep public class org.cocos2dx.** { *; }
-dontwarn org.cocos2dx.**
-keep public class com.chukong.** { *; }
-dontwarn com.chukong.**

# google play service
-keep class com.google.android.gms.** { *; }
-dontwarn com.google.android.gms.**

-keep class * extends java.util.ListResourceBundle {
    protected Object[][] getContents();
}

-keep public class com.google.android.gms.common.internal.safeparcel.SafeParcelable {
    public static final *** NULL;
}

-keepnames @com.google.android.gms.common.annotation.KeepName class *
-keepclassmembernames class * {
    @com.google.android.gms.common.annotation.KeepName *;
}

-keepnames class * implements android.os.Parcelable {
    public static final ** CREATOR;
}

#sdkbox
-keep class com.sdkbox.** { *; }
-dontwarn com.sdkbox.**

注间: Proguard 只在 Release 编译时有效 (比如 cocos run -m release) debug 不会触发 Proguard.