Unity SDK

Available in Classic and VPC

This guide provides instructions on how to use the GAMEPOT Unity SDK in the Unity environment. You can integrate the game and dashboard by installing the SDK and configuring the environment.

Requirements

The recommended specifications required to use GAMEPOT SDK for Unity are as follows:

• Unity minimum version: 2022.3.44f1 or later
• If you need support for older versions of Unity, contact us through Contact us.

Install SDK and configure environment

You can install the GAMEPOT Unity SDK, configure the environment, and integrate the game and GAMEPOT dashboard to use features required for the game development.

The GAMEPOT SDK supports the following languages.

• Korean, English, Italian, Thai, Vietnamese, Japanese, Chinese (Simplified/Traditional), Indonesian, German, Spanish, French

When you reset GAMEPOT, the interface will automatically display in the language you selected during registration. Languages not supported will be displayed in English.

SDK installation

To install the GAMEPOT Unity SDK and configure your project in Unity, follow these steps.

1. Download the latest version from the Official Unity GitHub repository.
2. In Unity, go to Assets > Import Package > Custom Package..., then select and import the nbasesdk-unity-plugin-[version].unitypackage file.
   • Starting with GAMEPOT 3.0, it is distributed via Maven distribution and CocoaPods, and integrates with dozens of external libraries with simple setup per device.

It is installed including External Dependency Manager for Unity, which enables you to install Android and iOS packages conveniently.

In NBase SDK Unity 3.0.18 or later, you can select the modules to use for Android and iOS from the Tools > GamePotSDK > Dependency Manager menu. Clicking Apply Dependencies updates Assets/NBaseSDK/Editor/NBaseSDKDependencies.xml and runs the Android dependency resolution. Use Advanced Mode only if you need to specify versions manually.

Set Gradle for Android

Follow the Gradle setup procedure required for Android builds in order.

1. In Player Settings, under Publishing Settings, select Custom Main Gradle Template and Custom Gradle Properties Template.
   
2. Raise the minimum API level to 24.
   
3. Click the Assets > External Dependency Manager > Android Resolver > Settings menus, in that order, and then deselect the Enable Auto-Resolution and Explode AARs fields.
   
4. Open Tools > GamePotSDK > Dependency Manager, select the Android module to use, and click Apply Dependencies.

If you need to add modules not provided by the Dependency Manager, you can edit Assets/NBaseSDK/Editor/NBaseSDKDependencies.xml directly. The following is an example that defines the dependency packages required by default for using the NBase SDK.

What are dependency modules?
Dependency modules are modules for using external SDKs, such as io.nbase:nbase-adapter-provider-google for Google login, which must be installed with the module provided by Google.

XML example:

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

• When using Google login and Google Play Store payment

XML example:

<dependencies>
    <androidPackages>
        <androidPackage spec="io.nbase:nbasesdk:3.0.98"/>
        <androidPackage spec="io.nbase:nbase-adapter-provider-google:3.0.13"/>
        <androidPackage spec="io.nbase:nbase-adapter-billing-googleplay:3.0.12" />
    </androidPackages>
    <iosPods>
        <iosPod name="NBase" version="3.0.67" minTargetSdk="15.1" />
        <iosPod name="NBaseAdapterProviderGoogle" version="3.0.58" minTargetSdk="15.1" />
    </iosPods>
</dependencies>

Supported AOS-dependent modules are as follows:

Email and guest logins are applied to the base module.

If the Dependency Manager is unable to automatically resolve Android dependencies, click Assets > External Dependency Manager > Android Resolver > Force Resolve in the Unity Editor.

After defining in Dependencies.xml, if you run Force Resolve, the content defined in the mainTemplate.gradle file is automatically defined as implementation, and this content must be completed to import the relevant libraries when building.

Set iOS

Open Tools > GamePotSDK > Dependency Manager, select the iOS module to use, and click Apply Dependencies.

If you need to add a pod that is not provided by the Dependency Manager, you can directly edit the iosPods section in the Assets/NBaseSDK/Editor/NBaseSDKDependencies.xml file.

XML example:

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

If you want to install the necessary framework, such as Firebase, you can do so separately as shown below.

XML example:

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

If CocoaPods is not installed,
Click Assets > External Dependency Manager > iOS Resolver > Install Cocoapods within the Unity Editor.

Supported iOS dependent modules are as follows:

The following describes how to manually add essential dependency frameworks that require installation via Swift Package Manager.

1. In Xcode, go to Project Settings, and then enter the Package Dependencies settings.
   

2. Add https://github.com/apollographql/apollo-ios.git to the URL input field at the top right, search for it, select apollo-ios, and then add it with Add Package.

3. Add the Apollo and ApolloAPI modules displayed in the modal to the main target (Unity-iPhone) of your project.
   

   The following table, this section, describes the dependency modules added via Swift Package Manager.

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

Preparation

Before applying the GAMEPOT Unity SDK, verify the following essential configuration items.

1. Copy the project ID and project key from Dashboard > Project settings.
2. Add/edit login, store, and integration settings in Dashboard > Project settings.
3. See Configuration by login method for each login, set it in the console and add it to the dashboard.
4. Before in-app payment, see Configuration by store to set it in the console and add it to the dashboard.
5. Before in-app payment, register items in Dashboard > Payment > In-app for each payment store.

Reset

To perform an initialization, add the following code to the object used in the first scene loaded when the game starts.

C# Example:

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());
       });
     }
 }

• Parameters

The following table describes the parameters required for initialization.

See the following table for store identifiers.

• Callback

The following table describes the information passed to the initialization callback.

Reset (event receipt)

First, you need to create a script that receives NBase events.
This script is called NBaseListener and can be placed on any object in the scene. It is recommended that you call the DontDestroyOnLoad method to ensure that the object exists permanently.

The image below illustrates an example of configuring the NBaseListener script in a scene.

C# Example:

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

Login feature

This section describes how to authenticate users using various authentication methods through the login feature.

Use login feature

Use the following code to use the SDK login feature that functions when clicking the login button according to the login UI implemented by the developer. Before that, you must complete all the console and dashboard settings required for login to work properly.

C# Example:

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;
});

If you use the pop-up provided by the SDK when updating or checking, add the following code.

C# Example:

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

The following table describes the service types used in the login feature.

• User

The following table describes the fields of the User object.

AppStatus

The following table describes the fields of the AppStatus object.

Login UI provided by SDK

You can use the login UI provided by GAMEPOT SDK in a completed form.
Use the following code to call the login UI provided by the SDK.

C# Example:

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;
});

Auto login (optional)

After initialization, it may attempt to automatically log in with the last authentication method you logged in with. We recommend checking the last login provider type before attempting automatic login.

C# Example:

// Check the last login provider type.
string lastProviderType = NBaseSDK.NBase.getLastProviderType();

if (lastProviderType != Provider.none.ToString())
{
    // Attempt automatic login only if last login information is available.
    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
{
    // No last login information
    Debug.Log("No last login provider found");
}

The getLastProviderType() method returns the last logged-in provider type.

The signInLastLoggedIn() method attempts automatic login using the last authentication method used to log in.

• Callback

The following table describes the values passed to the automatic login callback.

Log out

Use the following code to log out of your GAMEPOT account.

C# Example:

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());
        // Processing logic after successful logout
    }
});

• Callback

The following table describes the values passed to the logout callback.

Membership withdrawal

Use the following code to use the SDK membership withdrawal feature.

C# Example:

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());
        // Logic after successful membership withdrawal
    }
});

• Parameters

The following table, this section, describes the parameters that must be passed for a membership withdrawal.

• Callback

The following table describes the callback values for membership withdrawal.

Self-authentication with username and password (optional)

This is an authentication method that allows users to log in using their email address and password. It performs user authentication based on the user's email address and password.

C# Example:

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

Log in with credentials (optional)

Use the following code to log in using credentials (access tokens) obtained from external social accounts.

C# Example:

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());
    }
});

• Parameter

The following table describes the parameters required for credential login.

• Callback

The following table describes the credential login callback values.

External account integration feature

This section describes the feature that allows you to integrate and manage external social accounts with your GAMEPOT user account.

Use external account integration feature

Use the following code to integrate another social account with your current GAMEPOT user account.

C# Example:

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);
        // Processing logic after successful account integration
    }
});

• Parameter

The following table describes the parameters required for account integration.

• Callback

The following table describes the callback values for account integration.

Integrate Steam account on Unity Standalone

To integrate your current Steam client account with your logged-in GAMEPOT user account, configure and call the following steps.

1. Install Steamworks.NET in your Unity project.
2. Register the Steamworks app ID and web API key in the Steam integration settings on the GAMEPOT dashboard.
3. For local testing, enter your Steamworks app ID in steam_appid.txt. If you are running the built executable directly outside of Steam, place this file in the same folder as the executable. Do not include the test steam_appid.txt file in your release build.
4. Initialize the Steam API while logged into the Steam client.
5. Complete the GAMEPOT login, then call createLinking using Provider.steam.

C# Example:

NBaseSDK.NBase.createLinking(Provider.steam.ToString(), (linkingId, error) => {
    if (error != null)
    {
        Debug.LogError($"Steam account linking failed: {error.Code} / {error.Message}");
        return;
    }

    Debug.Log($"Steam account linking succeeded: {linkingId}");
});

The createLinking method in Standalone currently supports only the Steam provider. If you pass a provider such as Google or Apple, an error callback will be returned. If Steamworks.NET is not installed, the Steam API has not been initialized, the Steam client is not logged in, or the authentication ticket issuance fails, the operation will not be treated as successful and will return an error.

After successful integration, you can save the returned linkingId or retrieve it again using getLinkedLists. To unintegrate, you must pass this linking ID rather than the provider string.

Check integration list

Use the following code to check the list of social accounts currently integrated with your GAMEPOT user account. The same API is used in Unity Standalone as well.

C# Example:

NBaseSDK.NBase.getLinkedLists((linkings, error) => {
    if (error != null)
    {
        // getLinkedLists Failed
        Debug.Log("getLinkedLists Failed: " + error.Message.ToString());
    }
    else
    {
        // getLinkedLists Success
        if (linkings == null || linkings.Count == 0)
        {
            Debug.Log("No linked accounts");
            return;
        }

        foreach (NBaseSDK.NBase.Linking linking in linkings)
        {
            Debug.Log($"getLinkedLists Success: {linking.Provider} / {linking.Id}");
        }
    }
});

• Callback

The following table describes the values provided when checking the account integration list.

• Linking

The following table describes the fields of the Linking object.

Remove integration

To remove a specific social account integration from your current GAMEPOT user account, use the following code. Unity Standalone uses the same API, and you need to pass the Linking.Id found in getLinkedLists.

C# Example:

NBaseSDK.NBase.deleteLinking(linkingId, (status, error) => {
    if (error != null)
    {
        // deleteLinking Failed
        Debug.Log("deleteLinking Failed: " + error.Message.ToString());
    }
    else if (status)
    {
        // deleteLinking Success
        Debug.Log("deleteLinking Success: " + status.ToString());
        // Processing logic after successful integration removal
    }
    else
    {
        Debug.LogWarning("deleteLinking returned false");
    }
});

• Parameter

The following table describes the parameters required for account integration removal.

• Callback

The following table describes the callback values for account integration removal.

Check app status

Use the following code to check the client's current maintenance/update status.

C# Example:

NBaseSDK.NBase.checkAppStatus((status, error) =>
{
    if (error != null)
    {
        Debug.LogError("checkAppStatus Failed: " + error.Message);
        return;
    }

    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, (popupStatus, popupError) => {
                // 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, (popupStatus, popupError) => {
                // Popup handling
            });
            */
            break;
    }
});

Unity Standalone information

Standalone refers to builds for Mac, Windows, and Linux.
The GAMEPOT SDK supports cross-platform, but the features supported by mobile and Standalone are different, so see the table below to plan your development.

Newtonsoft.Json crash

The NBase Unity SDK uses Unity's Newtonsoft JSON package to parse API requests. JSON is one of the most commonly used libraries, so there is a possibility that you already have JSON in your project and you will get the following library duplication error.

In this case, you can delete the Newtonsoft.Json file in the Plugins/Standalone path or delete the JSON library already in the project and use Unity's JSON. Unity's JSON package has been modified to work with the Unity engine and is a fully supported version of IL2CPP.

Troubleshooting

This section provides information on common errors and how to resolve them.

Q. UnityPlayerActivity.java uses or overrides a deprecated API.
A. Select Edit > Project Settings > Player > Publishing Settings > Custom Properties Gradle Template.

Q. error:1E08010C:DECODER routines::unsupported
A. This occurs when the Google authentication key value does not match. See the Google Play Store guide and enter the key correctly.

Q. Minimum API level increase notice
A. Raise the minimum API level from 22 to 24.
The image below illustrates where to adjust the API level.

Q. Authorization failed: Error Domain=AKAuthenticationError Code=-7026
A. Add Sign In with Apple by clicking TARGETS > +Capability.
The image below illustrates the page for adding the Sign in with Apple feature.

Q. Couldn't get credential from result.10: Developer console is not set up correctly
A. This error may occur because the client ID of the web application type is not set in Google Cloud Console > Set credentials > OAuth 2.0 client ID.

Q. 16: Cannot find a matching credential.
A. This error can occur when the Google Cloud Console > Set credentials > OAuth 2.0 client ID is not registered.

Q. java.lang.NoClassDefFoundError: Failed resolution of: Lcom/android/billingclient/api/BillingClient;
A. Add the following code.

XML example:

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

Q. (iOS) A crash occurs when the app is launched, and the "/AdapterProviderFacebook' (no such file)" error is confirmed.
A. Add Xcode TARGETS → General → Frameworks, Libraries, and Embedded Content → AdapterProviderFacebook.xcframework.

Q. (iOS) After launching, an "'/usr/lib/swift/NBase.framework/NBase' (no such file, not in dyld cache)" error occurs.
A. Add NBase.xcframework as shown below.
The image below illustrates the process of adding NBase.xcframework to the project.

Q. (iOS) In the iOS 18 environment, an "NSBundle file:///System/Library/Frameworks/Metal.framework/ principal class is nil because all fallbacks have failed" error occurs.

A. Open the Edit Scheme window (shortcut: CMD + SHIFT + ,), deselect API Validation from the Metal field.
The image below illustrates where to disable the Metal API Validation option.