PlaySuper LogoPlaySuper

Unity SDK Guide

Complete guide for integrating PlaySuper into your Unity games

🎮 Unity SDK Guide

Complete guide for integrating PlaySuper rewards into your Unity games.

Installation

Step 1: Install GPM

The PlaySuper Unity SDK relies on the GPM package which is available Unity Asset Store. Therefore, you must install and set up GPM before installing PlaySuper's Unity SDK. Follow these steps:

  1. Click on Add to My Assets on the GPM asset page. This will link the package to your Unity account.

  2. In your Unity Project, go to Window > Package Manager and click on My Assets in the dropdown menu at the top of the window.

  3. Select Game Package Manager from the list of available assets, and click Import.

  4. After importing GPM, navigate to Tools > GPM > Manager. In the left panel, select WebView and click Install.

Step 2: Install PlaySuper's Unity SDK

There are two ways to install the PlaySuper's Unity SDK:

  • From GitHub
  • From OpenUPM (Open Unity Package Manager)

Note: For development/testing, you can grab our dev build from: v1.2.2

Option A: OpenUPM-CLI

If you have the OpenUPM CLI installed, you can install the OpenUPM registry with the following command:

openupm add com.playsuper.unity-sdk

Option B: Import from GitHub

  1. Download and extract the latest Source Code release from unity-sdk github.

  2. Navigate to Window > Package Manager in your Unity Project.

  3. Click on the plus icon in the navigation bar at the top, and choose Add Package from Disk. This will open a file navigation dialog.

  4. Navigate to the extracted unity-sdk-public folder, which was downloaded from Github in step 1. Select the package.json file to import the Unity SDK package.

Setup

Unity 6 Compatibility Notes

Special considerations for Unity 6 compatibility - check the expandable section in the original documentation.

Android Configuration

  1. Open File > Build Settings and make sure the Unity project is configured for Android. If you don't see Android selected, follow the below steps:

    • Click on Android to select it, in the left panel
    • Click on the Switch Platform button at the bottom right corner of the window. This will change the platform configuration of your Unity project to Android.

  2. Open Edit > Project Settings in your Unity project

  3. Under Player, navigate to publisher settings for Android

  4. Tick the Custom Main Gradle Template and Custom Gradle Properties Template options. This will create two files inside Assets/Plugins/Android

  5. Open the Assets/Plugins/Android/mainTemplate.gradle file. You need to edit this file to include the following dependencies:

dependencies {
    implementation 'androidx.browser:browser:1.4.0'
    implementation 'androidx.appcompat:appcompat:1.4.2'
    // other dependencies...
}

6. Open the `Assets/Plugins/Android/gradleTemplate.properties` file and add the following line to the end of the file:

```properties
android.useAndroidX=true

Usage

To integrate PlaySuper rewards into your game, follow these steps in order:

1. Import the SDK

Add the following line of code at the top of your C# script:

using PlaySuperUnity;

2. Initialize the SDK

To initialize the SDK instance, you need to call the Initialize method within a C# script. First, log in to the PlaySuper console and navigate to your game's settings to copy the API key. Click on the View API keys button at the top-right to view and copy an API key.

Once you have the API key, use the following code snippet to initialize the SDK:

void Awake()
{
    PlaySuperUnitySDK.Initialize("YOUR_API_KEY");
}

Make sure you change API Key in your code, when you Regenerate the API Key from console. The API Key on console must match the API key in code.

You can call the Initialize method in any top-level script that loads in your first scene, inside the Awake lifecycle method. This ensures that the PlaySuper SDK is available across all scenes. Alternatively, you can also create a new GameObject specifically for SDK initialization and place it in your first scene.

3. Create Player

Before distributing coins, you need to create a player on PlaySuper. Use the CreatePlayerWithUuid method with a unique identifier for your player (e.g., your game's internal user ID):

async void CreatePlayer()
{
    // Use your game's unique player identifier
    string playerUuid = "your-unique-player-id";

    var response = await PlaySuperUnitySDK.Instance.CreatePlayerWithUuid(playerUuid);

    if (response != null && response.data != null)
    {
        Debug.Log($"Player created with ID: {response.data.playerId}");
    }
    else
    {
        Debug.LogError("Failed to create player");
    }
}

Parameters:

ParameterTypeDescription
uuidstringA unique identifier for the player in your game (required)

Response:

FieldTypeDescription
data.playerIdstringThe PlaySuper player ID
data.messagestringStatus message

You only need to create a player once. Store the player UUID and reuse it for login.

4. Login Player

After creating a player, log them in using the LoginFederatedByStudio method. This authenticates the player and saves their auth token for subsequent API calls:

async void LoginPlayer()
{
    // Use the same UUID used during player creation
    string playerUuid = "your-unique-player-id";

    var response = await PlaySuperUnitySDK.Instance.LoginFederatedByStudio(playerUuid);

    if (response != null && !string.IsNullOrEmpty(response.access_token))
    {
        Debug.Log("Player logged in successfully!");
        // Auth token is automatically saved - you can now distribute coins
    }
    else
    {
        Debug.LogError("Failed to login player");
    }
}

Parameters:

ParameterTypeDescription
uuidstringThe same unique identifier used during player creation (required)

Response:

FieldTypeDescription
access_tokenstringThe authentication token (automatically saved by SDK)
messagestringStatus message

The auth token is automatically persisted by the SDK. Players will remain logged in across game sessions until the token expires.

5. Distribute Coins

Once the player is logged in, you can distribute coins. Navigate to the PlaySuper console, go to the Coins Page from the sidebar, and copy the desired coinId you want to distribute.

async void DistributeCoins()
{
    string coinId = "YOUR_COIN_ID";
    int amount = 100;

    await PlaySuperUnitySDK.Instance.DistributeCoins(coinId, amount);
    Debug.Log($"Distributed {amount} coins");
}

Parameters:

ParameterTypeDescription
coinIdstringThe coin ID from PlaySuper console (required)
amountintNumber of coins to distribute (required)

If the player is not logged in or there's a network error, the transaction is automatically stored locally and will be synced when the player logs in and connectivity is restored.

6. Open PlaySuper Store

Open the PlaySuper rewards store where players can view and redeem their coins. The store automatically uses the auth token if the player is logged in.

void OpenStore()
{
    PlaySuperUnitySDK.Instance.OpenStore();
}

Opening Store on a Specific Route

You can open the store directly to a specific page by passing a custom URL:

// Open store to a specific route
void OpenStoreToRewards()
{
    string customUrl = "https://store.playsuper.club/rewards";
    PlaySuperUnitySDK.Instance.OpenStore(customUrl);
}

// Open store with UTM tracking
void OpenStoreWithTracking()
{
    string customUrl = "https://store.playsuper.club/gcommerce";
    string utmContent = "main_menu_button";
    PlaySuperUnitySDK.Instance.OpenStore(customUrl, utmContent);
}

Parameters:

ParameterTypeDescription
urlstringOptional - custom URL to open a specific store route
utmContentstringOptional - UTM content parameter for analytics tracking

7. Check Login Status

To check if the user is logged into PlaySuper:

bool isLoggedIn = PlaySuperUnitySDK.IsLoggedIn();
if (isLoggedIn)
{
    Debug.Log("User is logged in");
}
else
{
    Debug.Log("User is not logged in - need to login again");
}

The auth token is stored locally on the device and remains valid until it expires. Use IsLoggedIn() to check if the token is still valid. If it returns false, call LoginFederatedByStudio() again to get a new token.

async void Start()
{
    // Check if already logged in from previous session
    if (!PlaySuperUnitySDK.IsLoggedIn())
    {
        // Token expired or not logged in - login again
        await PlaySuperUnitySDK.Instance.LoginFederatedByStudio(playerUuid);
    }

    // Now ready to distribute coins and open store
}

8. Get User Balance

To retrieve the user's coin balances:

PlaySuperUnitySDK.Instance.GetBalance((List<CoinBalance> balances) => {
    foreach (CoinBalance balance in balances)
    {
        Debug.Log($"Coin: {balance.name}, Amount: {balance.amount}");
    }
});

The CoinBalance class contains the following properties:

PropertyTypeDescription
idstringCoin ID
namestringCoin Name
urlstringCoin Image URL
amountintCoin Balance

Complete Integration Example

Here's a complete example showing the full integration flow:

using UnityEngine;
using PlaySuperUnity;
using System.Collections.Generic;

public class PlaySuperManager : MonoBehaviour
{
    private string playerUuid = "unique-player-id-123";

    void Awake()
    {
        // Step 1: Initialize SDK
        PlaySuperUnitySDK.Initialize("YOUR_API_KEY");
    }

    async void Start()
    {
        // Step 2: Create player (only needed once per player)
        await CreatePlayer();

        // Step 3: Login player
        await LoginPlayer();
    }

    async Task CreatePlayer()
    {
        var response = await PlaySuperUnitySDK.Instance.CreatePlayerWithUuid(playerUuid);
        if (response?.data != null)
        {
            Debug.Log($"Player created: {response.data.playerId}");
        }
    }

    async Task LoginPlayer()
    {
        var response = await PlaySuperUnitySDK.Instance.LoginFederatedByStudio(playerUuid);
        if (response != null)
        {
            Debug.Log("Logged in successfully!");
        }
    }

    // Call this when player earns coins in your game
    public async void OnPlayerEarnedCoins(int amount)
    {
        await PlaySuperUnitySDK.Instance.DistributeCoins("YOUR_COIN_ID", amount);
    }

    // Call this to open the rewards store
    public void OnOpenStoreButtonClicked()
    {
        PlaySuperUnitySDK.Instance.OpenStore();
    }
}

Handling Offline Scenarios

The PlaySuper SDK has built-in offline support for coin distribution. Here's how it works:

Automatic Offline Storage

When you call DistributeCoins, the SDK automatically handles offline scenarios:

  • No auth token: Transaction stored locally
  • Network error: Transaction stored locally
  • Server error: Transaction stored locally

When connectivity is restored and the player logs in, pending transactions are automatically synced.

Manual Network Check (Optional)

If you want to provide UI feedback about network status:

private bool IsOnline()
{
    return Application.internetReachability != NetworkReachability.NotReachable;
}

public async void DistributeCoinsWithFeedback(string coinId, int amount)
{
    if (!IsOnline())
    {
        // Show offline indicator to user
        Debug.Log("You're offline. Coins will be synced when connected.");
    }

    // SDK handles storage automatically
    await PlaySuperUnitySDK.Instance.DistributeCoins(coinId, amount);
}

Best Practices

  1. Always use async/await for DistributeCoins, CreatePlayerWithUuid, and LoginFederatedByStudio
  2. Check login status before critical operations using PlaySuperUnitySDK.IsLoggedIn()
  3. Handle the player flow - Create player once, then login on each session
  4. Store your player UUID - Keep the same UUID for the same player across sessions

Touchpoints

Touchpoints are visual widget configurations that define how rewards, products, and promotional content appear in your game. The SDK provides methods to fetch touchpoint data for rendering custom UI.

Fetching Touchpoints

All touchpoint methods are in the TouchpointManager class under the PlaySuperUnity namespace.

// Fetch by name (recommended)
TouchpointResponse store = await TouchpointManager.GetTouchpointByName("flash-sale-card", "coin-uuid-abcd");

// Fetch by ID
TouchpointResponse offer = await TouchpointManager.GetTouchpointById(
    "6f9a5737-0247-4a71-89eb-b5d02212f179",
    "coin-uuid-abcd"
);

// List all touchpoints
TouchpointListResponse list = await TouchpointManager.ListTouchpoints("coin-uuid-abcd");

Processing Touchpoint Data

if (store?.nodes?.Length > 0)
{
    TouchpointNode node = store.nodes[0];

    // Access typed properties
    Debug.Log($"Layout: {node.layoutHint}");

    // Background images
    string bgImage = node.background?.images?[0];

    // Title text
    string titleText = node.title?[0]?.text;
    string titleColor = node.title?[0]?.color;

    // CTA button
    string ctaAction = node.cta?.action;
    string ctaText = node.cta?.text;

    // Style hints
    bool timerEnabled = node.GetStyleHint<bool>("timerEnabled", false);

    // Reward data (if node has rewardId)
    if (node.HasReward)
    {
        HydratedReward reward = node.GetReward();
        string brandName = reward?.brandName;
    }
}

For complete touchpoint API documentation including all data types, example responses, and advanced usage patterns, see the Touchpoints API Reference.

Troubleshooting

Common issues and solutions:

  • API Key Issues: Ensure your API key matches between console and code
  • Environment Mismatch: If you are using Dev environment then pass isDev=true while initializing SDK
  • Android Build Issues: Verify gradle templates are properly configured
  • Network Issues: Implement proper offline handling as described above
  • GPM Installation: Make sure GPM WebView is properly installed

Support

Need help with Unity integration?

PlaySuper Console

Learn how to use the PlaySuper Console to manage your rewards

Embedding the PlaySuper Store in Web

How to embed the PlaySuper store in your web applications

On this page

🎮 Unity SDK GuideInstallationStep 1: Install GPMStep 2: Install PlaySuper's Unity SDKOption A: OpenUPM-CLIOption B: Import from GitHubSetupUnity 6 Compatibility NotesAndroid ConfigurationUsage1. Import the SDK2. Initialize the SDK3. Create Player4. Login Player5. Distribute Coins6. Open PlaySuper StoreOpening Store on a Specific Route7. Check Login StatusRecommended Login Flow8. Get User BalanceComplete Integration ExampleHandling Offline ScenariosAutomatic Offline StorageManual Network Check (Optional)Best PracticesTouchpointsFetching TouchpointsProcessing Touchpoint DataTroubleshootingSupport