‹ 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.h
让 RootviewController
实现 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
-
URL 1:
- Identifier:
com.google.ReverseClientId
- Url schemes:
com.googleusercontent.apps.777734739048-cdkbeieil19d6pfkavddrri5o19gk4ni
(use this as sample, or put your very own application’s url scheme)
- Identifier:
-
URL 2:
- Identifier:
com.google.BundleId
- URL schemes:
com.sdkbox.gpg
(use this as sample or put your own application’s bundle id)
- Identifier:
更多资料
在官方文档中查看更多的相关信息
重点注意事项
如果您升级到了 Xcode7, 则需要以下额外步骤来确保插件工作正常:
禁用应用程序安全传输策略
添加以下项到 plist:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
添加后的文件内容看起来就像这样:
禁止 Bitcode 支持
您必须禁止 Bitcode 的支持,否则将会编译失败。
游戏全屏配置
如果您的游戏不同时支持横竖屏,则必须在 Xcode 中选中 Requires full screen
,否则将不会通过 Apple 的审核。
canOpenURL 白名单
取决于您使用哪些插件。需要在 info.plist
的 LSApplicationQueriesSchemes
下添加名单。
关于 Creator 工程
Creator 导出工程会修改工程的配置, 这可能会影响 SDKBox 对工程的配置修改. 所以可以有以下做法(任选其一):
- 保存导出工程中的修改, 对于 SDKBox 来说可能有这些文件(mk, gradle, gradle.properties, AppDelegate.cpp, ...), 导出后再恢复对应该文件
- 在每一次 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"
- 在
./frameworks/runtime-src/Classes/AppDelegate.cpp
中调用如下代码:
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 有两个回调 AuthActionStarted
和 AuthActionFinished
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代表您处理以下任务:
- 管理网络连接以创建和维护实时多人游戏室(虚拟构造,实现在同一游戏会话中的多个玩家之间的网络通信,并且允许玩家彼此直接发送数据)。
- 提供选择用户界面, 邀请玩家加入房间,随机寻找玩家进行自动匹配,或两者的组合。
- 在实时多人游戏的生命周期内,在Google Play游戏服务服务器上存储参与者和房间状态信息。
- 向玩家发送房间邀请和更新。通知会显示在玩家登录的所有设备上(除非已禁用)。
更多信息请参见: Real-time Multiplayer 文档
Turn-based multiplayer
在基于回合的多人游戏中,在多个玩家之间传递共享一个状态,并且在一个回合中只有一个玩家具有修改共享状态的许可。 玩家根据由游戏确定的游戏顺序异步轮流。 您的游戏可以使用Google Play游戏服务提供的回合制多人API来管理以下任务:
- 邀请玩家加入回合制多人游戏比赛,随机寻找玩家与您的游戏匹配,或两者的组合。 Google Play游戏服务可让您在比赛中最多容纳8位参与者。
- 将参与者和匹配状态信息存储在Google服务器上,并在基于回合的匹配生命周期内与所有参与者异步分享更新的匹配数据。
- 发送匹配邀请并向玩家发送通知。 通知会显示在玩家登录的所有设备上(除非禁用)。
更多信息请参见: 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, 等中都有提示.
手动集成
如果用 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.h
让 RootviewController
实现 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
-
URL 1:
- Identifier:
com.google.ReverseClientId
- Url schemes:
com.googleusercontent.apps.777734739048-cdkbeieil19d6pfkavddrri5o19gk4ni
(这里要使用你自己的 application URL scheme)
- Identifier:
-
URL 2:
- Identifier:
com.google.BundleId
- URL schemes:
com.sdkbox.gpg
(这里要使用你自己的 application 包名)
- Identifier:
更多信息
在官方文档上有更多信息
把 plugin/jsbindings
文件夹中所有的头文件和源文件都拷贝到你的工程的 Classes
文件夹中.
把刚刚拷贝的文件拖动到 Xcode 中或使用 File -> Add files to... 来添加.
Android 手动集成
SDKBox 支持三种 Android 工程, command-line, eclipse 和 Android Studio.
- command-line 和 eclipse 类型的项目,
<project_root>
指代proj.android
. - Android Studio 类型的项目,
<project_root>
指代proj.android-studio
.
拷贝文件
把安装包中的 plugin/android/libs
目录下的如下 jar 文件拷贝到你的工程中的
-
如果你使用 cocos2d-x 源码,拷贝 jar 文件到:
Android command-line:
cocos2d/cocos/platform/android/java/libs
Android Studio:
cocos2d/cocos/platform/android/libcocos2dx/libs
-
如果你使用 cocos2d-js 或者 lua ,拷贝 jar 文件到:
Android command-line:
frameworks/cocos2d-x/cocos/platform/android/java/libs
Android Studio:
frameworks/cocos2d-x/cocos/platform/android/libcocos2dx/libs
-
如果你使用 cocos2d-x 预编译包,拷贝 jar 文件到:
Android command-line:
proj.android/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
- 找到 AppActivity.java 文件
find . -name "AppActivity.java"
- 把
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
-
如果您使用 cocos2d-x 源代码,假设您在
proj.android
目录下,那么您可以在如下位置找到Cocos2dxActivity.java
文件:../../cocos2d-x/cocos/platform/android/java/src/org/cocos2dx/ lib/Cocos2dxActivity.java
-
如果您使用 cocos2dx-x 预编译库, 假设您在
proj.android
目录下,那么您可以在如下位置找到Cocos2dxActivity.java
文件:./src/org/cocos2dx/lib/Cocos2dxActivity.java
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
- 修改
Cocos2dxActivity.java
文件,导入如下包:
import android.content.Intent;
import com.sdkbox.plugin.SDKBox;
- 然后,修改
Cocos2dxActivity
类的onCreate(final Bundle savedInstanceState)
函数,添加一个调用语句SDKBox.init(this);
。添加的位置非常重要,必须在调用onLoadNativeLibraries();
之后。如下:
onLoadNativeLibraries();
SDKBox.init(this);
-
最后, 我需要提供合适的 overrides 方法的代码。这里有一些约定如下。
-
如果这个被列出的方法没有在
SDKBox
中定义,那么__定义它__。 -
如果这个被列出的方法已经被定义在
SDKBox
中,那么请调用这个在SDKBox
中的__同名方法__。
-
@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)
- 编辑
project.properties
文件在其中加一个Proguard
配置. 例如:
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.