iOS

本文旨在介绍如何设置 Game Center 身份验证，让您的游戏可以使用 Player Network 登录鉴权服务通过 Game Center 渠道登录。

前提条件

1. 在 Apple Developer 上配置 iOS 应用

1. 创建 App ID

在 Apple 开发者平台上注册并登录 Apple 开发者账号。
在顶部导航栏中点击 Account，并选择 Certificates, IDs & Profiles 下的 Identifiers。
点击蓝色添加图标（+）。
选择 App IDs 后，点击 Continue。
选择 App 后，点击Continue。
输入 Description 和 Bundle ID。
- Description：游戏应用的名称或描述。
- Bundle ID：游戏应用的唯一标识符，包含在 App ID 中。
在 Capabilities 下选择 Sign in with Apple 后，点击 Continue。
点击 Register 创建 App ID。

2. 设置 App Store Connect

登录 App Store Connect。
选择 App。
点击App（+），选择添加 App。
根据在步骤1中获得的 Bundle ID，创建 App Store Connect App。
选择 Feature > Game Center，进入 Game Center 配置页面。
启用 Game Center 功能。

更多信息，可参见：https://developer.apple.com/help/app-store-connect/

排行榜

在左侧导航栏选择 Game Center ，在右侧选择 Add leaderboards 创建新的排行榜或者 Add an achievement 添加成就设置。

图片：GameCenter iTunes Connect

根据需要输入详细信息。

info

点击每个字段输入框旁边的问号（?）图标，将给出详细解释。

点击 Storage 保存已配置的排行榜。

图片：GameCenter Leaderboard

info

用户可根据需要添加多个排行榜。排行榜支持多种语言，每种语言都必须单独添加。成就设置与排行榜设置类似。

步骤1：为 Game Center 登录配置 SDK

在目标项目的 Signing & Capabilities 页面，Bundle Identifier 必须是在 App Store Connect 中已注册的 iOS App 应用。
否则，当用户登录 Game Center 时，会收到提示不支持 Game Center 的错误信息。
在目标项目的 Signing & Capabilities 页面，添加 + Capability 添加 Game Center。

info

系统库依赖项 GameKit.framework 将自动添加到 Xcode 中的项目依赖项中。

图片：Game Center Xcode

步骤2：添加 Game Center 登录

在 iOS 10 之后的版本中，Game Center 将继续作为一项服务存在，但用户设备上将不再出现单独的 Game Center 应用程序。用户可以进入设置 > Game Center 登录并继续使用相关功能。

用户在游戏内登录 Game Center 主要有两种情况：

已经通过设置 > Game Center 登录：执行后台登录，并显示 Welcome back, xxxx 横幅。整个登录过程不会中断游戏。
未通过设置 > Game Center 登录：游戏内会弹出 Game Center 登录框。如果用户取消登录三次，将无法访问游戏内的 Game Center 登录框，需要返回到设置 > Game Center 手动登录 Game Center。

注册登录相关回调。

Unity
Unreal Engine

// Add callbacks
public void AddAuthObserver()
{
    INTLAPI.AddAuthResultObserver(OnAuthResultEvent);
}

// Remove callbacks
public void RemoveAuthObserver()
{
    INTLAPI.RemoveAuthResultObserver(OnAuthResultEvent);
}

// Process the INTLAuthResult callback
public void OnAuthResultEvent(INTLAuthResult AuthResult)
{
    Debug.Log($"MethodID: {AuthResult.MethodId}");
    
    string methodTag = "";
    switch (AuthResult.MethodId)
    {
        case (int)INTLMethodID.INTL_AUTH_LOGIN:
            methodTag = "Login";
            break;
        case (int)INTLMethodID.INTL_AUTH_BIND:
            methodTag = "Bind";
            break;
        case (int)INTLMethodID.INTL_AUTH_AUTOLOGIN:
            methodTag = "AutoLogin";
            break;
        case (int)INTLMethodID.INTL_AUTH_QUERY_USER_INFO:
            methodTag = "QueryUserInfo";
            break;
        case (int)INTLMethodID.INTL_AUTH_GET_AUTH_RESULT:
            methodTag = "GetAuthResult";
            break;
    }
}

C++ Event Handling (above v1.15)

//configure callback
FINTLAuthEvent authEvent;
authEvent.AddUObject(this, &OnAuthResult_Implementation);
UINTLSDKAPI::SetAuthResultObserver(authEvent);
// Remove callbacks
UINTLSDKAPI::GetAuthResultObserver().Clear();

void OnAuthResult_Implementation(FINTLAuthResult ret)
{ 
    UE_LOG(LogTemp, Warning, TEXT("MethodID: %d"), ret.MethodId);
}

Unreal Event Handling

void OnAuthResult_Implementation(FINTLAuthResult ret)
{ 
    UE_LOG(LogTemp, Warning, TEXT("MethodID: %d"), ret.MethodId);
}

调用 AutoLogin 接口自动登录。
- Unity
- Unreal Engine
INTLAPI.AutoLogin();
UINTLSDKAPI::AutoLogin();

在自动登录失败时调用 Login 接口使玩家手动登录。

Unity
Unreal Engine

INTLAPI.Login(INTLChannel.GameCenter);

UINTLSDKAPI::Login(EINTLLoginChannel::kChannelGameCenter);

与游戏后台同步客户端身份验证状态，等待最终验证结果。

步骤3：验收登录功能

在 Player Network SDK 日志中搜索关键字 "AuthResult" 确认渠道名称和 OpenID 是否正确返回。如果正确，则表明集成配置成功，登录功能已成功添加。

如果接入过程中遇到问题，请参见常见问题。

玩家限制

在成功登录 Game Center 后，GKLocalPlayer 对象会提供限制状态信息，游戏可以根据这些信息对功能进行限制：

isUnderage：判断玩家是否为未成年人。
isMultiplayerGamingRestricted：判断玩家是否可以加入多人游戏。
isPersonalizedCommunicationRestricted：判断玩家是否可以在设备上使用个性化通信功能。

Game Center 成就系统

Player Network SDK 提供了成就模块，在 iOS 上集成了 Game Center 成就功能。游戏可以通过此模块解锁成就、增加进度以及展示原生成就界面。

关于 Game Center 成就的设计与运营，可参见苹果官方文档。

前提条件

已完成本文前提条件中的 Game Center 配置，并在 App Store Connect 的 Game Center 中配置好成就。
调用成就接口前，玩家需已登录 Game Center，否则接口会通过回调返回 NEED_LOGIN 错误。
- 玩家可通过 Game Center 渠道直接登录；若游戏以其他渠道作为主登录方式，可开启 GAMECENTER_ENABLE_GC 配置（默认关闭），SDK 会在主渠道登录成功后自动完成 Game Center 授权。

注册成就回调

注册回调以接收成就操作结果。

Unity
Unreal Engine

// 添加成就回调
INTLAPI.AddAchievementResultObserver(OnAchievementResult);

// 移除成就回调
INTLAPI.RemoveAchievementResultObserver(OnAchievementResult);

// 处理成就结果
public void OnAchievementResult(INTLAchievementResult ret)
{
    Debug.Log($"Achievement MethodID: {ret.MethodId}, RetCode: {ret.RetCode}, Platform: {ret.Platform}");
}

// 注册成就回调
FINTLAchievementEvent achievementObserver;
achievementObserver.AddUObject(this, &UMyClass::OnAchievementResult);
UINTLSDKAPI::SetAchievementResultObserver(achievementObserver);

// 移除成就回调
UINTLSDKAPI::GetAchievementResultObserver().Clear();

void UMyClass::OnAchievementResult(FINTLAchievementResult ret)
{
    UE_LOG(LogTemp, Log, TEXT("Achievement MethodID: %d, RetCode: %d"), ret.MethodId, ret.RetCode);
}

解锁成就

通过成就 ID 解锁一个标准成就。

Unity
Unreal Engine

INTLAPI.UnlockAchievement("GameCenter", "achievement_id_here");

UINTLSDKAPI::UnlockAchievement(TEXT("GameCenter"), TEXT("achievement_id_here"), TEXT("{}"));

增加成就进度

对于增量成就，按指定值增加进度。

note

progress 为百分比增量（0–100），累加到当前进度上并以 100% 封顶。例如进度 30% 时传入 20，更新为 50%。

Unity
Unreal Engine

// 将成就进度增加 20%
INTLAPI.IncrementAchievement("GameCenter", "achievement_id_here", 20);

// 将成就进度增加 20%
UINTLSDKAPI::IncrementAchievement(TEXT("GameCenter"), TEXT("achievement_id_here"), 20, TEXT("{}"));

展示成就界面

展示 Game Center 原生成就界面。玩家关闭界面后会通过回调返回结果。

Unity
Unreal Engine

INTLAPI.ShowAchievementsUI("GameCenter");

UINTLSDKAPI::ShowAchievementsUI(TEXT("GameCenter"), TEXT("{}"));

Game Center 排行榜

Player Network SDK 提供了排行榜模块，在 iOS 上集成了 Game Center 排行榜功能。游戏可以通过此模块提交分数以及展示原生排行榜界面。

关于 Game Center 排行榜的设计与运营，可参见苹果官方文档。

note

在 iOS 上，SubmitScore 与 ShowLeaderboardUI 依赖 GKLeaderboard 新接口，要求 iOS 14.0 及以上。在低于 iOS 14 的设备上调用，接口会通过回调返回 NOT_SUPPORT 错误。

前提条件

已完成本文前提条件中的 Game Center 配置，并在 App Store Connect 的 Game Center 中创建好排行榜，记录排行榜 ID（Leaderboard ID）。
调用排行榜接口前，玩家需已登录 Game Center（同成就前提条件），否则接口会通过回调返回 NEED_LOGIN 错误。

注册排行榜回调

注册回调以接收排行榜操作结果。

Unity
Unreal Engine

// 添加排行榜回调
INTLAPI.AddLeaderboardResultObserver(OnLeaderboardResult);

// 移除排行榜回调
INTLAPI.RemoveLeaderboardResultObserver(OnLeaderboardResult);

// 处理排行榜结果
public void OnLeaderboardResult(INTLLeaderboardResult ret)
{
    Debug.Log($"Leaderboard MethodID: {ret.MethodId}, RetCode: {ret.RetCode}, Platform: {ret.Platform}");
}

// 注册排行榜回调
FINTLLeaderboardEvent leaderboardObserver;
leaderboardObserver.AddUObject(this, &UMyClass::OnLeaderboardResult);
UINTLSDKAPI::SetLeaderboardResultObserver(leaderboardObserver);

// 移除排行榜回调
UINTLSDKAPI::GetLeaderboardResultObserver().Clear();

void UMyClass::OnLeaderboardResult(FINTLLeaderboardResult ret)
{
    UE_LOG(LogTemp, Log, TEXT("Leaderboard MethodID: %d, RetCode: %d"), ret.MethodId, ret.RetCode);
}

提交分数

向指定排行榜提交一个分数。

Unity
Unreal Engine

INTLAPI.SubmitScore("GameCenter", "leaderboard_id_here", 1000);

UINTLSDKAPI::SubmitScore(TEXT("GameCenter"), TEXT("leaderboard_id_here"), 1000, TEXT("{}"));

展示排行榜界面

展示 Game Center 原生排行榜界面。玩家关闭界面后会通过回调返回结果。

note

leaderboardId 传入具体的排行榜 ID 时，仅展示该排行榜；传入空字符串（""）时，展示全部排行榜列表。

Unity
Unreal Engine

// 展示指定排行榜
INTLAPI.ShowLeaderboardUI("GameCenter", "leaderboard_id_here");

// 展示全部排行榜
INTLAPI.ShowLeaderboardUI("GameCenter", "");

// 展示指定排行榜
UINTLSDKAPI::ShowLeaderboardUI(TEXT("GameCenter"), TEXT("leaderboard_id_here"), TEXT("{}"));

// 展示全部排行榜
UINTLSDKAPI::ShowLeaderboardUI(TEXT("GameCenter"), TEXT(""), TEXT("{}"));

前提条件​

步骤1：为 Game Center 登录配置 SDK​

步骤2：添加 Game Center 登录​

步骤3：验收登录功能​

玩家限制​

Game Center 成就系统​

前提条件​

注册成就回调​

解锁成就​

增加成就进度​

展示成就界面​

Game Center 排行榜​

前提条件​

注册排行榜回调​

提交分数​

展示排行榜界面​

前提条件

步骤1：为 Game Center 登录配置 SDK

步骤2：添加 Game Center 登录

步骤3：验收登录功能

玩家限制

Game Center 成就系统

前提条件

注册成就回调

解锁成就

增加成就进度

展示成就界面

Game Center 排行榜

前提条件

注册排行榜回调

提交分数

展示排行榜界面