Unity SDK

可在Classic/VPC环境下使用。

下面介绍在Unity中使用GAMEPOT Unity SDK关联游戏与仪表盘的方法。从安装SDK开始进行环境配置，即可整合游戏开发所需的功能。

配置要求

为使用Unity的GAMEPOT SDK，所需的配置要求如下。

• 最低配置：2022.3.44f1以上
• 如需获得低版本的Unity支持，请通过咨询频道进行咨询。

SDK安装及环境配置

安装GAMEPOT Unity SDK后配置环境并关联GAMEPOT仪表盘和游戏，即可使用游戏开发所需的功能。

GAMEPOT SDK支持的语言如下所示。

• 韩语、英语、意大利语、泰语、越南语、日语、中文（简体/繁体）、印尼语、德语、西班牙语、法语

运行应用时，将根据设备语言自动显示SDK支持的语言，不支持的语言将显示为英语。

安装SDK

安装GAMEPOT Unity SDK后，在Unity配置项目的方法如下。

1. 请在 Unity官方发布的GitHub 页面下载最新版本。
2. 在Unity中依次点击 Assets > Import Package > Custom Package... 菜单后导入nbase-unity-plugin-[version].unitypackage文件。
   • 从GAMEPOT 3.0起通过Maven和CocoaPods发布，并可通过各个设备的简单设置与多种外部库集成。

安装时包括External Dependency Manager for Unity在内，可以方便地安装Android和iOS包。

Android Gradle设置

请按顺序执行Android构建所需的Gradle设置步骤。

1. 在Player Settings中选择Publishing Settings下的Custom Main Gradle Template和Custom Gradle Properties Template。
   
2. 将Minimum API Level提升至24。
   
3. 依次点击Assets > External Dependency Manager > Android Resolver > Settings菜单后，取消勾选Enable Auto-Resolution和Explode AARs项。
   
4. 请按照下图所示，在编辑器中打开Dependency设置文件并确认相关配置。
   

以下是定义使用NBase SDK时默认所需的依赖包的文件。如需附加功能，可在下方文件中添加项目，以便在Android和iOS中使用模块。

什么是Dependency modules？
此为使用外部SDK时所需的模块。在使用Google登录时，必须同时安装以适配器形式提供的模块，如io.nbase:nbase-adapter-provider-google。

XML示例：

<?xml version="1.0" encoding="UTF-8"?>
<dependencies>
    <androidPackages>
        <androidPackage spec="io.nbase:nbasesdk:3.0.87"/>
    </androidPackages>
    <iosPods>
        <iosPod name="NBase" version="3.0.59" minTargetSdk="15.0" />
    </iosPods>
</dependencies>

• 使用Google登录和Google Play Store支付时

XML示例：

<dependencies>
    <androidPackages>
        <androidPackage spec="io.nbase:nbasesdk:3.0.87"/>
        <androidPackage spec="io.nbase:nbase-adapter-provider-google:3.0.10"/>
        <androidPackage spec="io.nbase:nbase-adapter-billing-googleplay:3.0.6" />
    </androidPackages>
    <iosPods>
        <iosPod name="NBase" version="3.0.59" minTargetSdk="15.0" />
        <iosPod name="NBaseAdapterProviderGoogle" version="3.0.56" minTargetSdk="15.0" />
    </iosPods>
</dependencies>

支持的依赖模块如下：

邮箱和访客登录适用于基础模块。

完成所有依赖项设置后，在Unity编辑器中点击Assets > External Dependency Manager > Android Resolver > Force Resolve。

配置Dependencies.xml后执行Force Resolve时，mainTemplate.gradle文件中定义的内容会自动以implementation的形式应用，只有完成这些设置后，才能在构建时下载相关的库。

iOS设置

打开/Assets/NBaseSDK/Editor/NBaseSDKDependencies.xml文件。

在"iosPods"和"/iosPods"之间添加所需的框架即可。默认情况下已添加必要的框架。

XML示例：

<?xml version="1.0" encoding="UTF-8"?>
<dependencies>
	<androidPackages>
        ...
	</androidPackages>
    <iosPods>
		<iosPod name="NBase" version="3.0.59" minTargetSdk="15.0" />
    </iosPods>
</dependencies>

如要安装Firebase等必要的框架，请按照如下方式另行添加。

XML示例：

<iosPods> 
       ...
        <iosPod name="FirebaseMessaging" version="10.20.0" minTargetSdk="9.0" />
        <iosPod name="Firebase/Analytics" version="10.15.0" minTargetSdk="9.0" />
        ...
</iosPods>

如果尚未设置CocoaPods，
请在Unity编辑器中点击Assets > External Dependency Manager > iOS Resolver > Install Cocoapods。

下方是通过Swift Package Manager手动添加额外所需的必要依赖框架的方法。

1. 在Xcode中转到项目设置，然后进入包依赖设置。
   

2. 在右上方的URL输入栏中添加https://github.com/apollographql/apollo-ios.git后搜索，在搜索结果中选择apollo-ios，然后通过Add Package添加。

3. 在弹出模态窗口中将Apollo和ApolloAPI模块添加到项目的主目标（Unity-iPhone）中。
   

   下表介绍通过Swift Package Manager添加的依赖模块。

   Name	Dependency modules	Location	Version	Framework
   	NBase	Apollo	https://github.com/apollographql/apollo-ios.git	1.15.2

前期准备

在应用GAMEPOT Unity SDK前，请如下确认所需的必要设置项目。

1. 在仪表盘 > 项目设置中复制项目ID和项目密钥。
2. 在仪表盘 > 项目设置中添加或修改登录、商店和关联的环境设置。
3. 登录时请参考各种登录方式的环境设置，在控制台中完成设置并添加到仪表盘。
4. 执行应用内支付前，参考商店环境设置，在控制台中完成设置并添加到仪表盘。
5. 执行应用内支付前，在每个商店的仪表盘 > 支付 > 应用内中登记商品。

重置

如要执行重置，在开始游戏时加载的第一个场景中使用的对象中添加以下代码。

C# 示例：

using UnityEngine;
using NBaseSDK;

 public class GamePotExample : MonoBehaviour
 {
     void Start()
     { 
       NBaseSDK.NBase.initialize(projectId, projectKey, [storeId], [language], [region], (init, error) => {
           if (error != null)
           {
               Debug.Log(error.Message);
               return;
           }
           Debug.Log(init.ToString());
       });
     }
 }

参数

下表介绍初始化所需的参数。

商店标识符请参考下表。

回调信息

下表介绍通过初始化回调传递的信息。

重置（接收事件）

首先要创建接收NBase事件的脚本。
该脚本叫作NBaseListener，可以放置在场景中的任何对象上。建议调用DontDestroyOnLoad方法，以确保该对象永久存在。

下图展示了在场景中配置NBaseListener脚本的示例。

C# 示例：

using UnityEngine;
using NBaseSDK;
public class NBaseListener: MonoBehaviour, NBaseEventListener
{
	void Start()
	{
        DontDestroyOnLoad(this.gameObject);
        NBaseSDK.NBase.SetEventListener(this);
    }	
}

登录功能

使用登录功能

如要使用根据开发商实现的登录UI点击登录按钮时操作的SDK登录功能，请使用下列代码。在此之前，必须完成登录所需的所有控制台和仪表盘设置才能正常工作。

C# 示例：

NBaseSDK.NBase.signIn(Provider.google.ToString(), (user, error) => {
    if (error != null)
    {
        if (error.Code == NBaseSDK.NBase.ErrorCode.MEMBER_WITHDRAW) // Withdrawal status
        {
            // Withdrawal
            Debug.Log(error.Message.ToString());    // Withdrawal message
        }
        else if (error.Code == NBaseSDK.NBase.ErrorCode.SERVICE_MAINTENANCE) // Maintenance
        {
            Debug.Log(error.Message.ToString());    // Maintenance message
            // case 1: Use in-game popup implemented directly by the developer
            // case 2: Call the code below to use the SDK's own popup
            // NBaseSDK.NBase.showAppStatusPopup(user?.AppStatus, (status, error) => {
            //     // Popup handling
            // });
        }
        else if (error.Code == NBaseSDK.NBase.ErrorCode.UPDATE_REQUIRED) // Update
        {
            Debug.Log(error.Message.ToString());    // Update message
            // case 1: Use in-game popup implemented directly by the developer
            // case 2: Call the code below to use the SDK's own popup
            // NBaseSDK.NBase.showAppStatusPopup(user?.AppStatus, (status, error) => {
            //     // Popup handling
            // });
        }
        else if (error.Code == NBaseSDK.NBase.ErrorCode.MEMBER_BANNED) // Access blocked
        {
            Debug.Log(error.Message.ToString());    // Block message
        }
        else 
        {
            // signIn Failed
            Debug.Log(error.Message.ToString());
        }
    }
    else
    {
        // signIn Success
        Debug.Log(user.ToString());
    }
    return;
});

如在更新或维护时使用SDK提供的自主弹窗，请添加下方代码。

C# 示例：

NBaseSDK.NBase.showAppStatusPopup(appStatus, (status, error) =>
{
    bool shouldClose = false;
    bool shouldNext = false;
    var closeValue = status.Close; 
    var nextValue = status.Next;

    if (closeValue != null)
    {
        if (bool.TryParse(closeValue.ToString(), out bool result))
        {
            shouldClose = result;
        }
    }

    if (shouldClose)
    {
        // App Close
    }

    if (nextValue != null)
    {
        if (bool.TryParse(nextValue.ToString(), out bool result))
        {
            shouldNext = result;
        }
    }

    if (shouldNext)
    {
        // Next, Optional update
    }
});

参数

下表介绍了在登录功能中使用的Provider值。

用户信息

下表介绍了用户对象的字段。

应用状态信息

下表介绍了AppStatus对象的字段。

SDK自主提供的登录UI

可以使用GAMEPOT SDK提供的完整的登录UI。
如要调用SDK提供的登录UI，请使用下列代码。

C# 示例：

NBaseSDK.NBase.openSignInUI((user, error) => {
    if (error != null)
    {
        if (error.Code == NBaseSDK.NBase.ErrorCode.MEMBER_WITHDRAW) // Withdrawal status
        {
            // Withdrawal
            Debug.Log(error.Message.ToString());    // Withdrawal message
        }
        else if (error.Code == NBaseSDK.NBase.ErrorCode.SERVICE_MAINTENANCE) // Maintenance
        {
            Debug.Log(error.Message.ToString());    // Maintenance message
            // case 1: Use in-game popup implemented directly by the developer
            // case 2: Call the code below to use the SDK's own popup
            // NBaseSDK.NBase.showAppStatusPopup(user?.AppStatus, (status, error) => {
            //     // Popup handling
            // });
        }
        else if (error.Code == NBaseSDK.NBase.ErrorCode.UPDATE_REQUIRED) // Update
        {
            Debug.Log(error.Message.ToString());    // Update message
            // case 1: Use in-game popup implemented directly by the developer
            // case 2: Call the code below to use the SDK's own popup
            // NBaseSDK.NBase.showAppStatusPopup(user?.AppStatus, (status, error) => {
            //     // Popup handling
            // });
        }
        else if (error.Code == NBaseSDK.NBase.ErrorCode.MEMBER_BANNED) // Access blocked
        {
            Debug.Log(error.Message.ToString());    // Block message
        }
        else 
        {
            // signIn Failed
            Debug.Log(error.Message.ToString());
        }
    }
    else
    {
        // signIn Success
        Debug.Log(user.ToString());
    }
    return;
});

自动登录（可选）

重置后，可能会尝试使用上次的登录认证方式自动登录。尝试自动登录前，建议先确认上次登录的Provider类型。

C# 示例：

// 确认上次登录的Provider类型
string lastProviderType = NBaseSDK.NBase.getLastProviderType();

if (lastProviderType != Provider.none.ToString())
{
    // 仅在存在上次登录信息时尝试自动登录
    NBaseSDK.NBase.signInLastLoggedIn((user, error) => {
        if (error != null)
        {
            if (error.Code == NBaseSDK.NBase.ErrorCode.MEMBER_WITHDRAW) // Withdrawal status
            {
                // Withdrawal
                Debug.Log(error.Message.ToString());    // Withdrawal message
            }
            else if (error.Code == NBaseSDK.NBase.ErrorCode.SERVICE_MAINTENANCE) // Maintenance
            {
                // Maintenance
                Debug.Log(error.Message.ToString());    // Maintenance message
                /* case 1: Use in-game popup implemented directly by the developer
                case 2: Call the code below to use the SDK's own popup
                NBaseSDK.NBase.showAppStatusPopup(user?.AppStatus, (status, error) => {
                    // Popup handling
                });
                */
            }
            else if (error.Code == NBaseSDK.NBase.ErrorCode.UPDATE_REQUIRED) // Update
            {
                // Update
                Debug.Log(error.Message.ToString());    // Update message
                /* case 1: Use in-game popup implemented directly by the developer
                case 2: Call the code below to use the SDK's own popup
                NBaseSDK.NBase.showAppStatusPopup(user?.AppStatus, (status, error) => {
                    // Popup handling
                });
                */
            }
            else if (error.Code == NBaseSDK.NBase.ErrorCode.MEMBER_BANNED) // Access blocked
            {
                // Access blocked
                Debug.Log(error.Message.ToString());    // Block message
            }
            else
            {
                // signIn Failed
                Debug.Log(error.Message.ToString());
            }
        }
        else
        {
            // signIn Success
            Debug.Log(user.ToString());
        }
    });
}
else
{
    // 上次登录信息不存在
    Debug.Log("No last login provider found");
}

getLastProviderType() 方法会返回上次登录的Provider类型。

signInLastLoggedIn() 方法将使用上次的登录认证方式自动登录。

回调信息

下表介绍了通过自动登录回调传递的值。

退出登录

如要使用SDK退出登录功能，请运用下列代码。

C# 示例：

NBaseSDK.NBase.signOut((status, error) => {
    if (error != null)
    {
        // signOut Failed
        Debug.Log("signOut Failed: " + error.Message.ToString());
    }
    else
    {
        // signOut Success
        Debug.Log("signOut Success: " + status.ToString());
        // 成功退出登录后的处理逻辑
    }
});

回调信息

下表介绍了通过退出登录回调传递的值。

注销会员

如要使用SDK会员注销功能，请使用下列代码。

C# 示例：

NBaseSDK.NBase.deleteMember(providerId, (status, error) => {
    if (error != null)
    {
        // deleteMember Failed
        Debug.Log("deleteMember Failed: " + error.Message.ToString());
    }
    else
    {
        // deleteMember Success
        Debug.Log("deleteMember Success: " + status.ToString());
        // 成功注销会员后的处理逻辑
    }
});

参数

下表介绍了在会员注销时必须传递的参数。

回调信息

下表介绍了会员注销回调值。

使用ID和密码自行认证（可选）

这是允许用户使用邮件地址和密码登录的认证方法。
系统根据用户的邮件地址和密码进行用户身份验证，该功能在基于邮件/密码的传统身份验证系统中起着重要的作用。

C# 示例：

NBaseSDK.NBase.signInWithPassword(username, password, (user, error) => {
    if (error != null)
    {
        Debug.Log(error.Message.ToString());
        return;
    }
});

使用资格证明登录（可选）

若需使用从外部获取的社交账户凭证（Access Token）登录，请使用以下代码。

C# 示例：

NBaseSDK.NBase.signInWithCredential(Provider.google.ToString(), providerToken, (user, error) => {
    if (error != null)
    {
        if (error.Code == NBaseSDK.NBase.ErrorCode.SERVICE_MAINTENANCE) // Maintenance
        {
            // Maintenance
            Debug.Log("Maintenance: " + error.Message.ToString());
            /* case 1: Use in-game popup implemented directly by the developer
            case 2: Call the code below to use the SDK's own popup
            NBaseSDK.NBase.showAppStatusPopup(user?.AppStatus, (status, error) => {
                // Popup handling
            });
            */
        }
        else if (error.Code == NBaseSDK.NBase.ErrorCode.UPDATE_REQUIRED) // Update
        {
            // Update
            Debug.Log("Update: " + error.Message.ToString());
            /* case 1: Use in-game popup implemented directly by the developer
            case 2: Call the code below to use the SDK's own popup
            NBaseSDK.NBase.showAppStatusPopup(user?.AppStatus, (status, error) => {
                // Popup handling
            });
            */
        }
        else
        {
            // signInWithCredential Failed
            Debug.Log("signInWithCredential Failed: " + error.Message.ToString());
        }
    }
    else
    {
        // signInWithCredential Success
        Debug.Log("signInWithCredential Success: " + user.ToString());
    }
});

参数

下表介绍了凭证登录时所需的参数。

回调信息

下表介绍了凭证登录回调值。

外部账户关联功能

本节介绍在GAMEPOT用户账户中关联和管理外部社交账户的功能。

使用外部账户关联功能

如要将其他社交账户与当前GAMEPOT用户账户关联，请使用下列代码。

C# 示例：

NBaseSDK.NBase.createLinking(Provider.google.ToString(), (linkingId, error) => {
    if (error != null)
    {
        // createLinking Failed
        Debug.Log("createLinking Failed: " + error.Message.ToString());
    }
    else
    {
        // createLinking Success
        Debug.Log("createLinking Success: " + linkingId);
        // 账户关联成功后的处理逻辑
    }
});

参数

下表介绍了账户关联所需的参数。

回调信息

下表介绍了账户关联回调值。

确认关联列表

如要查看与当前GAMEPOT用户账户相关联的社交账户列表，请使用下列代码。

C# 示例：

NBaseSDK.NBase.getLinkedLists((linkings, error) => {
    if (error != null)
    {
        // getLinkedLists Failed
        Debug.Log("getLinkedLists Failed: " + error.Message.ToString());
    }
    else
    {
        // getLinkedLists Success
        Debug.Log("getLinkedLists Success: " + linkings.ToString());
        // 确认关联列表后的处理逻辑
    }
});

回调信息

下表介绍了在确认账户关联列表时提供的值。

Linking对象

下表介绍了Linking对象的字段。

解除关联

若要在当前GAMEPOT用户账户中取消与特定社交账户的关联，请使用下列代码。

C# 示例：

NBaseSDK.NBase.deleteLinking(linkingId, (status, error) => {
    if (error != null)
    {
        // deleteLinking Failed
        Debug.Log("deleteLinking Failed: " + error.Message.ToString());
    }
    else
    {
        // deleteLinking Success
        Debug.Log("deleteLinking Success: " + status.ToString());
        // 成功取消关联后的处理逻辑
    }
});

参数

下表介绍了解除账户关联所需的参数。

回调信息

下表介绍了解除账户关联回调值。

确认应用状态

若要确认当前客户端的维护或更新状态，请使用下列代码。

C# 示例：

NBaseSDK.NBase.checkAppStatus((status, error) =>
    {
        switch(status.State)
        {
            case NBaseSDK.NBase.AppStatus.Status.SUCCESS:
                // SUCCESS
                break;
            case NBaseSDK.NBase.AppStatus.Status.FAILED:
                // FAILED
                break;
            case NBaseSDK.NBase.AppStatus.Status.MAINTENANCE:
                // Maintenance
                /* case 1: Use in-game popup implemented directly by the developer
                case 2: Call the code below to use the SDK's own popup
                NBaseSDK.NBase.showAppStatusPopup(status, (status, error) => {
                    // Popup handling
                });
                */
                break;
            case NBaseSDK.NBase.AppStatus.Status.UPDATE:
                // Update
                /* case 1: Use in-game popup implemented directly by the developer
                case 2: Call the code below to use the SDK's own popup
                NBaseSDK.NBase.showAppStatusPopup(status, (status, error) => {
                    // Popup handling
                });
                */
                break;
        }
    });

Unity Standalone介绍

Standalone指用于Mac、Windows和Linux的构建版本。
虽然GAMEPOT SDK支持跨平台，但由于移动端和Standalone支持的功能有所不同，请参考下表制定开发计划。

Newtonsoft.Json冲突

NBase Unity SDK使用Unity的Newtonsoft JSON包来解析API请求。由于JSON是最常用的库之一，所以项目中已存在JSON，并可能会出现以下库重复错误。

该情况下，删除Plugins/Standalone路径下的Newtonsoft.Json文件，或删除项目中已有的JSON库后使用Unity的JSON即可。Unity的JSON包已经修改为可与Unity引擎配合使用，并且是完全支持IL2CPP的版本。

解决问题

Q. UnityPlayerActivity.java uses or overrides a deprecated API.
A. 请勾选Edit > Project Settings > Player > Publishing settings > Custom Properties Gradle Template。

Q. error:1E08010C:DECODER routines::unsupported
A. 此问题是由于Google身份验证密钥值不匹配导致的，请参阅Google Play Store指南输入正确的密钥。

Q. 除ONE Store或GAMEPOT Beta等官方Maven地址以外，Maven或jitpack.io中均不提供下载。
Unity中出现了以下错误。

文本示例：

Could not determine the dependencies of task ':unityLibrary:compileReleaseAidl'.
> Could not resolve all task dependencies for configuration ':unityLibrary:releaseCompileClasspath'.
     > Could not find io.nbase:nbasesdk:0.0.71-beta.
         Required by:
                 project :unityLibrary

没有使用官方公共Maven的模块必须按如下方式输入Maven地址。配置NBaseSDKDependencies文件时，请一并输入Maven地址。

XML示例：

<!-- # ONE Store -->
<androidPackage spec="com.onestorecorp.sdk:sdk-iap:21.01.00"/>
    <repositories>
        <repository>https://repo.onestore.co.kr/repository/onestore-sdk-public</repository>
    </repositories>
</androidPackage>

<!-- # NBase Beta maven 仓库 -->
<androidPackage spec="io.nbase:nbasesdk:3.0.84"/>
    <repositories>
        <repository>https://repo.nbase.io/repository/nbase-releases/</repository>
    </repositories>
</androidPackage>

还可以添加jitpack.io地址。

Q. minimum API Level提升说明
A. 将基础API Level从22提升至24。
下图显示了调整API Level的位置。

Q. Authorization failed: Error Domain=AKAuthenticationError Code=-7026
A. 点击TARGETS > +Capability，并添加Sign in with Apple。
下图显示了添加Sign in with Apple功能的界面。

Q. Couldn't get credential from result.10: Developer console is not set up correctly
A. 出现该错误的原因可能是由于未在Google Cloud Console > 用户认证信息 > OAuth 2.0客户端ID中设置网络应用程序类型的客户端ID。

Q. 16: Cannot find a matching credential.
A. 当Google Cloud Console > 用户认证信息 > OAuth 2.0客户端ID未注册时，可能会出现此错误。

Q. java.lang.NoClassDefFoundError: Failed resolution of: Lcom/android/billingclient/api/BillingClient;
A. 请添加以下代码。

XML示例：

<androidPackage spec="com.android.billingclient:billing:7.0.0" /> 

Q. （iOS）运行应用时发生崩溃，出现"/AdapterProviderFacebook' (no such file)"错误
A. 请添加Xcode TARGETS → General → Frameworks, Libraries, and Embedded Content → AdapterProviderFacebook.xcframework。

Q. （iOS）运行后发生"'/usr/lib/swift/NBase.framework/NBase' (no such file, not in dyld cache)"错误
A. 添加NBase.xcframework，如下所示。
下图显示了将NBase.xcframework添加到项目的过程。

Q. （iOS）在iOS 18环境中发生"NSBundle file:///System/Library/Frameworks/Metal.framework/ principal class is nil because all fallbacks have failed"错误

A. 打开Edit Scheme窗口（快捷键：CMD + SHIFT + ,），然后取消勾选Metal项的API Validation。
下图显示了禁用Metal API Validation选项的位置。