Integration Guide

Last updated 1 year ago

Integration Guide

Introduction

The KAP Games SDK is a lightweight, seamless integration between a web3 Unity game and the KAP Games platform. The SDK can be used for tracking player actions within the game, which is in turn used for Battle Pass rewards, CPE calculations, and analytics.

This guide will walk you through setting up the SDK and go over the functionalities offered. For more information, see SDK Reference for details on the SDK API.

The SDK currently supports Unity WebGL builds. Supporting additional platforms, including Android, iOS, Windows, and Mac, is in development.

Before You Begin

The SDK is designed to only work with games that are hosted on the website and will not work correctly if run locally or hosted on a different domain. For help with local development, please contact us to receive access to our dev environment or refer to the section for working with the SDK locally.

Setup

Download the SDK using the and import it into your project.

To enable the SDK for use within your project code, you must first load the SDK and its associated scripts by calling the LoadSDK method as early as possible in your game code.

using KapGames;

bool result = await KapGamesSDK.LoadSDK();
if (result == true)
{
  Console.WriteLine("SDK loaded successfully!");
}
else
{
  Console.WriteLine("Failed to load SDK.");
}

User Initialization/Authentication

Once the SDK has successfully loaded, it must be initialized with a KAP Games user for many of the methods below to work. Assuming that the current player is on the KAP Games website and logged into their account, you can use the InitializeSDK method to setup the SDK with their user information. Once initialized the current user's information (ex. username) will be accessible to your game with the KapGamesSDK.LocalUser property, and the remaining SDK methods with become usable.

  using KapGames;

  bool result = await KapGamesSDK.InitializeSDK();
  if (result == true)
  {
    Console.WriteLine($"SDK initialized for {KapGamesSDK.LocalUser.username}!");
  }
  else
  {
    Console.WriteLine("Failed to initialize SDK, user not logged in.");
  }

If the call to InitializeSDK fails, it is most likely because the current player is not logged into their KAP Games account. From the SDK you can prompt the user to login with the LoginUser method which will authenticate them and initialize the SDK with their information automatically.

  using KapGames;

  bool result = await KapGamesSDK.InitializeSDK();
  if (result == true)
  {
    Console.WriteLine($"{KapGamesSDK.LocalUser.username} was logged in!");
  }
  else
  {
    Console.WriteLine("User rejected the login prompt.");
  }

Scores

From the SDK you can query for scores and report new scores on behalf of a KAP Games user. Reported scores can optionally contribute Battle Pass experience to the player achieving the score.

Currently, creating new leaderboards is not supported from within the SDK. If you would like to create a new scoreboard for your game, please contact KAP Games support.

To retrieve scores from the API, you can pass the ID of the leaderboard to the LoadScores method, which will return a list of all the scores in descending order.

  using KapGames;

  int scoreboardId = 1;
  var request = await KapGamesSDK.LoadScores(scoreboardId);
  if (request.status == KapGames.RequestStatus.Success)
  {
      Console.WriteLine("Succesfully loaded scores.");
      Console.WriteLine($"Scores: {request.result}")
  }
  else
  {
      Console.WriteLine("Failed to load scores.");
  }

For adding a new score to the leaderboard, you can call the ReportScore method which will take the initialized user and add a new score to the scoreboard for them.

  using KapGames;

  int scoreboardId = 1;
  int scoreValue = 25;
  var request = await KapGamesSDK.ReportScore(scoreboardId, scoreValue);
  if (request.status == KapGames.RequestStatus.Success && request.result == true)
  {
      Console.WriteLine("Succesfully reported score.");
  }
  else
  {
      Console.WriteLine("Failed to report score.");
  }

Achievements

Achievements work similarly to scores where you can use the SDK query for and update achievement progress for the currently initialized user. Reported achievements can optionally contribute Battle Pass experience to the player who earned the achievement.

To fetch the achievement progress:

  using KapGames;

  int achievementId = 1;
  var request = await KapGamesSDK.LoadAchievements(achievementId);
  if (request.status == KapGames.RequestStatus.Success)
  {
      Console.WriteLine("Succesfully loaded achievements.");
      Console.WriteLine($"Progress: {request.result[0].progress}")
  }
  else
  {
      Console.WriteLine("Failed to load achievements.");
  }

To update achievement progress:

  using KapGames;

  int achievementId = 1;
  int newProgress = 100;
  var request = await KapGamesSDK.ReportAchievement(achievementId, newProgress);
  if (request.status == KapGames.RequestStatus.Success && request.result == true)
  {
      Console.WriteLine("Succesfully reported achievement.");
  }
  else
  {
      Console.WriteLine("Failed to report achievement.");
  }

Assets

On the KAP Games site, users can link wallets to their accounts to use assets such as NFTs in game. You can integrate with this feature to query the NFT assets that a player has in all of the wallets linked to a user's account simultaneously. To do this you can pass a tuple of the blockchain id (ex. 137 for Polygon) and contract address to retrieve all NFT assets for that contract/chain id pair for all of the user's linked wallets. Alternatively, you can only include the chain id and omit the contract address field to return a list of all NFTs owned by that user on the provided chain.

  using KapGames;

  List<KapGames.ContractChainPair> pairs = new List<KapGames.ContractChainPair>();
  // will fetch all Polygon NFTs
  pairs.Add(new KapGames.ContractChainPair() { chainId = "137" });
  // will fetch Ethereum NFTs only for the given contract
  pairs.Add(new KapGames.ContractChainPair() { chainId = "1", address = "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D" });
  var request = await KapGamesSDK.GetAssets(pairs);
  if (request.status == KapGames.RequestStatus.Success)
  {
      Console.WriteLine("Succesfully loaded assets.");
      Console.WriteLine($"Assets: {request.result.results}")
  }
  else
  {
      Console.WriteLine("Failed to load assets.");
  }

The KAP Games SDK currently supports the following blockchains:

Ethereum Mainnet
Polygon
Binance Smart Chain
Arbitrum One
Solana

Offline Mode

Because most of the KAP Games SDK methods require authenticated user information, the SDK will only work when the WebGL build is embedded in a page within the KAP Games site. As a workaround to test your integration with the SDK, you can load the SDK in offline mode to return statically defined data. To do this, call the LoadSDK method with the offline_mode parameter set to true.

using KapGames;

bool result = await KapGamesSDK.LoadSDK(true);

Download

PreviousKAP Games SDK NextAPI Reference