Monetizr Challenges SDK for Unity

This SDK is used to communicate with Monetizr challenges API.

Installation

Clone the repository and import monetizr_challenges_unity_sdk_1.0.unitypackage into your project using Assets/Import Package/Custom Package....

Usage

You have to create and use one instance of ChallengesClient class and use it to communicate with the Monetizr Challenges API. You also have to set the current user's information in ChallengesClient.playerInfo (at least the identifier) to use the SDK. Challenge list can be retrieved using GetList. Whenever a progress is being made by player, UpdateChallenge has to be called. When the challenge is done, a claim button must be shown in the challenge menu and ClaimChallenge must be called whenever player clicks on the 'claim'.

Reference

Detailed Documentation

Monetizr.Challenges namespace

ChallengesClient

ChallengesClient(string apiKey, int timeout = 30) – creates an instance of ChallengesClient and sets the API key used by the SDK to apiKey.
GetList() – gets a list of challenges available to a player.
GetSingle(string id) – gets a single challenges identified by id.
UpdateStatus(Challenge challenge, int progress, Action onSuccess, Action onFailure) – updates the player's progress.
ClaimChallenge(Challenge challenge, Action onSuccess, Action onFailure) – must be called when player click the claim button on a completed challenge.
playerInfo – used to get and set player's information.

AssetsHelper

Download2DAsset(Challenge.Asset asset, Action<Challenge.Asset, Sprite> onAssetDownloaded) – downloads a 2D asset and returns it as a Sprite in onAssetDownloaded callback.

DownloadAssetData(Challenge.Asset asset, Action<Challenge.Asset, byte[]> onAssetDownloaded) – Downloads any type of asset and returns its data as an array of bytes in onAssetDownloadedCallback.

PlayerInfo

location – location of the current user (the location is used for challenges that are targeted for a specific region, for challenges without regional targeting is not being used).
age – age of the current user (used for challenges that are age specific, for challenges without age without age restrictions is not being used).
gameType – type of the game (used for challenges that are targeted for a specific game types).
playerId – a unique identifier of the user (mandatory).

Challenge

id – identification number of the challenge (must be passed to UpdateChallenge and ClaimChallenge)
title – title of the challenge (must be visible in the challenge menu).
content – description of the challenge (must be visible in the challenge menu).
progress – players progress (must be visible in the challenge menu).
reward – type of reward when the challenge is done (created for each game individually).
assets – a list of assets of the challenge (see Challenge.Asset).

Challenge.Asset

id – identification number of the asset (can be ignored).
type – type of the asset (icon, banner, 3DObject).
title – name of the asset (can be used as a key-value pair identifier).
url – the location of the asset.

---

Sample Code

To test if everything works, create a script with the following code and attach it to an object in your scene. If Challenges are set up correctly, you will see a list of challenges appear on that object in the inspector after the game starts.

using System.Collections.Generic;
using UnityEngine;
using Monetizr.Challenges;

public class MonetizrChallengesTest : MonoBehaviour
{
    [SerializeField]
    List<Challenge> challenges;

    private ChallengesClient challengesClient;

    private void Awake()
    {
        challengesClient = new ChallengesClient("your_api_key")
        {
            playerInfo = new PlayerInfo("City", 18, "action", "user")
        };

        UpdateChallengesList();
    }

    private async void UpdateChallengesList()
    {
        challenges = await challengesClient.GetList();
    }
}

Documentation

ChallengesClient

There should only be one instance of ChallengesClient in your project.
Remember to set the value of ChallengesClient.playerInfo.

challengesClient = new ChallengesClient("your_api_key")
{
    playerInfo = new PlayerInfo("City", 18, "action", "user")
};

GetList()

async Task<List<Challenge>> GetList()

Use GetList() to retrieve the list of all challenges available to the player.
If retrieving challenges from the server fails, an empty List will be returned.

GetSingle()

async Task<Challenge> GetSingle(string id)

Use GetSingle() to retrieve a single challenge with a matching ID.
If retrieving the challenge from the server fails null will be returned.

UpdateStatus()

async Task UpdateStatus(Challenge challenge, int progress, Action onSuccess = null, Action onFailure = null)

Use UpdateStatus() to update progress of the given challenge.
Progress gets clamped to a range between 0 and 100.
After status update attempt, depending on server response either onSuccess or onFailure will be invoked.

Claim()

async Task Claim(Challenge challenge, Action onSuccess = null, Action onFailure = null)

Use Claim() to mark the challenge as claimed by the player.
After claim attempt, depending on server response either onSuccess or onFailure will be invoked.

---

AssetsHelper

AssetsHelper is a static class that lets you download assets associated with challenges.

StartCoroutine(AssetsHelper.Download2DAsset(challenges[0].assets[0], (asset, sprite) => { image.sprite = sprite; }, () => Debug.Log("Asset download failed")));

Download2DAsset()

static IEnumerator Download2DAsset(Challenge.Asset asset, Action<Challenge.Asset, Sprite> onAssetDownloaded, Action onDownloadFailed = null)

Use Download2DAsset() to download assets of type icon or banner.
If asset is successfuly downloaded, a sprite will be generated and returned in onAssetDownloaded.
If asset download fails onDownloadFailed will be invoked.

DownloadAssetData()

static IEnumerator DownloadAssetData(Challenge.Asset asset, Action<Challenge.Asset, byte[]> onAssetDownloaded, Action onDownloadFailed = null)

Use DownloadAssetData() to download any type of an asset as an array of bytes. This allows for custom handling of 2D, 3D or any other type of asset types.
If asset is successfuly downloaded, an array of bytes will be returned in onAssetDownloaded.
If asset download fails onDownloadFailed will be invoked.