# Engage players automatically

Welcome! These documentation pages will guide you through the integration of Kibotu into your game.

Kibotu helps mobile game developers treat their players with auto-generated daily quests, weekly challenges, personal offers, and marketing visuals, which leads to higher retention and revenue.

We use custom AI models and automation to allow mobile games to deliver new, production-ready content daily.


# Integration

In a nutshell, the integration involves sending basic user interaction events (triggers) with parameters in order to receive personalized visual assets and metadata that treat players with quests, challenges, and personal offers.

<figure><img src="/files/kuyhLuuCEYkANG55ii2T" alt=""><figcaption></figcaption></figure>


# API Reference

## Intro

The Kibotu API is designed to facilitate the ongoing data flow between your game and Kibotu. This API serves as an entry point for accessing Kibotu's personalized assets and allows the creation of relevant segmentation by sending basic user interaction events and querying personalized content based on user and game contexts.

Kibotu provides multiple SDKs for different platforms. Please consult with your account manager before implementing direct API calls.

## API Conventions

#### **Base URL**

The base URL for all API requests is: **`https://api.kibotu.ai`**

#### **Authentication**

For authentication you need to provide an API key. Attach your API Key within the Request headers under the name "Authorization".

API Keys can be generated in the back office console. Alternatively, your account manager can provide you with an API Key.

#### R**equest and Response Formats**

Both request and response formats are JSON-encoded.


# Personal Offers

## Input parameters

#### UserId

Kibotu recognizes your users through their userId and keeps the same AB variation intact. Should a user be assigned to the control group, any subsequent requests will continue to return the control group consistently.

#### ContextObject

A union of GameContext and UserContext, such as level, coins, character, offered prize, country or geo-location, should be utilized. Please consult with your account manager to ensure proper segmentation parameters are set.

## Output parameters

#### AB Variation

Personalized banner (full URL of the personalized banner to be presented)

Personalization Key (For tracking further user actions, it is recommended to keep it along with the popup object to be able to attach to tracked events)

## Query for personalized content, specifically Personal Offers

<mark style="color:green;">`POST`</mark> `https://api.kibotu.ai/getPersonalizedBanner`

Check the `Input parameters` description listed above;

#### Request Body

| Name                                          | Type         | Description |
| --------------------------------------------- | ------------ | ----------- |
| userId<mark style="color:red;">\*</mark>      | String       |             |
| prizeTypes                                    | Array\[enum] |             |
| prizeKey<mark style="color:red;">\*</mark>    | String       |             |
| offerId<mark style="color:red;">\*</mark>     |              |             |
| zipCode                                       | String       |             |
| countryIso2<mark style="color:red;">\*</mark> | String       |             |
| languageIso2                                  | String       |             |

**Response**

{% tabs %}
{% tab title="200: OK Check `Output parameters` above;" %}

````
```json
imageFullUrl
kibotuMetadata
```
````

{% endtab %}

{% tab title="400: Bad Request " %}

```
Invalid input
```

{% endtab %}

{% tab title="401: Unauthorized " %}
Invalid authentication, check your API Key
{% endtab %}

{% tab title="403: Forbidden " %}
Invalid authorization, no permissions to perform the requested action
{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}
{% endtabs %}


# Quests

## Get All Quests

Query for all the quests that are currently active in game.

<mark style="color:green;">`POST`</mark> `https://api.kibotu.ai/quests/eligible`

**`Request Body` - Empty**

**`Response Body`**

```
{ 
    list: [
        {
            occasionId: ObjectId,
            game: ObjectId,
            enabled: true,
            name: String,
            targetFilter: {},
            from: Date,
            to: Date,
            countryCodesArray: [String],
            collectibleIconImage: String (URL),            
            milestones: [
                {
                    order: Number,
                    prizeTitle: String,
                    prizeImage: String (URL),
                    prizeSku: String,
                    goal: Number,
                    goalImage: String (URL),
                }
            ],
            triggers: {
                // First processing `state`
                state: {
                    // event triggers quest activation (from a list)
                    welcome: [{
                        eventName: String,
                        eventValue: Number,
                    }],
                    // event triggers progress steps (item collected, step++)
                    progress: [{
                        eventName: String,
                        eventValue: Number,
                    }],
                    // event triggers progress finalization (could be the same as progress, but could be different, like finishing a world)
                    finish: [{
                        eventName: String,
                        eventValue: Number,
                    }]
                },
                // Then processing `ui`
                ui: {
                    // event triggers showing a modal for welcome state
                    welcome: [{
                        eventName: String,
                        eventValue: Number,
                    }],
                    // event triggers showing a modal for progress state
                    progress: [{
                        eventName: String,
                        eventValue: Number,
                    }],
                    // event triggers showing a modal for finish state
                    finish: [{
                        eventName: String,
                        eventValue: Number,
                    }]
                }
            },
            graphics: {
                welcome: {
                    background: String (URL),
                    titleImage: String (URL),
        
                    base: String (URL),
                    preview: String (URL),
                },
                progress: {
                    background: String (URL),
                    titleImage: String (URL),
        
                    base: String (URL),
                    preview: String (URL),
                },
                finish: {
                    background: String (URL),
                    titleImage: String (URL),
        
                    base: String (URL),
                    preview: String (URL),
                },
            }
        }
    ] 
}
```

## Start Quest

Start the quest participation for the current player.

<mark style="color:green;">`POST`</mark> `https://api.kibotu.ai/quests/:questId/start`

**`Request parameters`**

* questId - The \_id of a quest is returned in the list of quests from the [Get All Quests](#get-all-quests) endpoint.

**`Request Body`**

```
{
    playerId: String
}
```

**`Response Body` - Empty on Success (http 200)**

## Get Player's Active Quest

Gets the quest that the current player is currently participating in.

<mark style="color:green;">`POST`</mark> `https://api.kibotu.ai/quests/active`

**`Request Body`**

```
{
    playerId: String
}
```

**`Response Body` - Identical to the Quest object listed in the** [**Get All Quests** ](#get-all-quests)**response, with an additional property**

```
{
    progress: Number
}
```

## Add Progress in Quest

Tracks the current player's progress in a specific quest.

<mark style="color:green;">`POST`</mark> `https://api.kibotu.ai/quests/:questId/trigger`

**`Request parameters`**

* questId - The \_id of a quest is returned from the [Get Player's Active Quest](#get-players-active-quest) endpoint.

**`Request Body`**

```
{
    playerId: String
}
```

**`Response Body` - on Success (http 200)**

```
{
    newValue: Number
}
```

## Finish Quest

Calculates whether the current player has won or lost this quest.

<mark style="color:green;">`POST`</mark> `https://api.kibotu.ai/quests/:questId/finish`

**`Request parameters`**

* questId - The \_id of a quest is returned from the [Get Player's Active Quest](#get-players-active-quest) endpoint.

**`Request Body`**

<pre><code><strong>{
</strong>    playerId: String
}
</code></pre>

**`Response Body` - Returns the latest milestone the player has achieved in this quest.**

```
{
    order: Number,
    prizeTitle: String,
    prizeImage: String (URL),
    prizeSku: String,
    goal: Number,
    goalImage: String (URL),
}
```

## Dismiss Quest

Removes the quest from the current player's [Active Quests](#get-players-active-quest) list (at the moment list is limited to 1).

<mark style="color:green;">`POST`</mark> `https://api.kibotu.ai/quests/:questId/finalize`

**`Request parameters`**

* questId - The \_id of a quest is returned from the [Get Player's Active Quest](#get-players-active-quest) endpoint.

**`Request Body`**

```
{
    playerId: String
}
```

**`Response Body`  - Empty on Success (http 200)**

## Verify Quest Prize

You will find this useful for server to server integration, when you want to verify the eligible prize of a finished quest (before committing the transaction of giving the prize)

<mark style="color:green;">`POST`</mark> `https://api.kibotu.ai/quests/:questId/verify-prize`

**`Request parameters`**

* questId - The \_id of a quest is returned from the [Get Player's Active Quest](#get-players-active-quest) endpoint.

**`Request Body`**

```
{
    playerId: String
}
```

**`Response Body`  - Returns the eligible prize for the player (http 200)**

```
{
    prizeSku: String
}
```


# Backoffice / Admin console

Kibotu's admin console gives you a clear view of the scheduled campaigns in the form of an events calendar and lets you create and edit campaigns, as well as render visual assets to populate these campaigns. It provides access to all of the rendered assets and offers the flexibility to adjust their targeting parameters.

The console also offers performance metrics. These range from a high-level overview of Kibotu's impact on your key KPIs.


# Implementing Unity SDK

Follow this guide on how to quick start with Kibotu Unity SDK

1. Access admin console\
   Login to the back office console at [`console.kibotu.ai`](https://console.kibotu.ai)<br>
2. Generate an API Key\
   Access [console.kibotu.ai/api-keys](https://console.kibotu.ai/api-keys) `and follow the key generation form, alternatively you may contact your account manager to get an API Key.`<br>
3. Install SDK

   In your unity project root open [`./Packages/manifest.json`](#user-content-fn-1)[^1] and add the following line to the dependencies section:<br>

   `"ai.kibotu.unity": "<https://github.com/KibotuAI/kibotu-unity.git",`

   \
   Open Unity project and the package should download automatically\
   \
   *(Currently we support Unity 2018.3 and above)*<br>
4. Configure SDK\
   \
   To use Kibotu SDK with Unity, you must first initialize it with your API key.\
   Open the unity project settings menu for Kibotu. \
   \
   `(Edit -> Project Settings -> Kibotu)` \
   \
   Enter your API key in the `Runtime Token` input field in the inspector.

<figure><img src="/files/aVbcLpYUeLQsSbJzDA2p" alt=""><figcaption><p>Project settings inspector for Kibotu</p></figcaption></figure>

1. Report a test event to Kibotu:\
   \
   `using kibotu;`\
   `Kibotu.Init();`\
   `Kibotu.Identify("test_user_id");`\
   `Kibotu.Track("TestEvent");`<br>
2. Check for success at admin console: [Settings -> Verify Integration](https://console.kibotu.ai/verify-integration)\
   \
   You should be able to see \`TestEvent\` in the list.\
   \
   *Note: Let it up to 60 seconds to be available in the console.*

[^1]:


# Reporting events

#### Notes:

1. Ensure that you invoke the .Init() and .Identify() methods in each session before tracking any events.
2. You might find it helpful to use Logs Live Tail in the [admin console](/documentation/backoffice-admin-console) to see the data coming in from your integration.

## Events to track

You might integrate the Kibotu.Track() method at the same level as your analytics reports, allowing you to report all user interactions to Kibotu.

Alternatively, you can choose to track only key events. A minimal integration would require just a few events. Please reach your account manager to establish a list of essential events. This would depend on how the potential segmentation of your players.

## Example events

The table below is an example of events reported by some of our customers.

Actually it reports only resuming the app and interacting with special offers.

<table data-full-width="false"><thead><tr><th width="292.3333333333333">EventName</th><th>Description</th><th>Required Properties</th></tr></thead><tbody><tr><td>AppStart</td><td>Application launched</td><td></td></tr><tr><td>AppRestore</td><td>Application focus resumed </td><td></td></tr><tr><td>SpecialOfferPopupOpened</td><td>Watched Special Offer</td><td>Attach Kibotu-Reference Properties * </td></tr><tr><td>SpecialOfferPopupDismissed</td><td>Dismissed Special Offer</td><td>Attach Kibotu-Reference Properties * </td></tr><tr><td>SpecialOfferPopupCtaClicked</td><td>Clicked Special Offer</td><td>Attach Kibotu-Reference Properties * </td></tr><tr><td>SpecialOfferPopupPurchased</td><td>Purchased Special Offer</td><td>Attach Kibotu-Reference Properties * </td></tr><tr><td>SpecialOfferInStoreViewed</td><td>In-app store - Watched item</td><td>Attach Kibotu-Reference Properties * </td></tr><tr><td>SpecialOfferInStoreCtaClicked</td><td>In-app store - Clicked item</td><td>Attach Kibotu-Reference Properties * </td></tr><tr><td>SpecialOfferInStorePurchased</td><td>In-app store - Purchased item</td><td>Attach Kibotu-Reference Properties * </td></tr><tr><td>SpecialOfferAdStarted</td><td>Ad Started</td><td>Attach Kibotu-Reference Properties * </td></tr><tr><td>SpecialOfferAdEnded</td><td>Ad Ended</td><td>Attach Kibotu-Reference Properties * </td></tr><tr><td>SpecialOfferAdClicked</td><td>Ad Clicked</td><td>Attach Kibotu-Reference Properties * </td></tr><tr><td>SpecialOfferAdSkipped</td><td>Ad Skipped</td><td>Attach Kibotu-Reference Properties * </td></tr><tr><td>SpecialOfferAdRewarded</td><td>Ad Rewarded</td><td>Attach Kibotu-Reference Properties * </td></tr><tr><td>* (event name as a string)</td><td>Any other monetization event<br>i.e. CoinsGained, CoinsSpent, GemsSpent</td><td></td></tr><tr><td>* (event name as a string)</td><td>Any other user-engagement event<br>i.e. MatchStarted, MatchFinished, LevelUp</td><td></td></tr></tbody></table>

## Kibotu-Reference Properties

For each special offer, when receiving an Asset from [getPersonalizationBanner](/unity-sdk/fetching-personal-offer) you need to store it with the special offer instance and provide it with the events of interaction with the special offer.

The actual reference fields are: `imageFullUrl` and `kibotuMetadata`.

This is a key property, as it enables Kibotu to "close the loop" by suggesting an offer to a player and receiving the interaction as performance feedback.

## Code example

Tracking an event without additional properties:

```
Kibotu.Track("AppStart");
```

Tracking an event with additional properties:

```
var context = new kibotu.Value();
context["prizeKey"] = "GoldPack8";
context["offerId"] = "3622d2-c8c8-4c52-851c-d71af05";
Kibotu.Track("SpecialOfferPopupDismissed", context);
```


# Fetching Personal Offer

Prepare properties object including user context and game context properties.

Follow the example:

```
var props = new Dictionary<string, object>();

props["prizeKey"] = "GoldPack8";
props["offerId"] = "3622d2-c8c8-4c52-851c-d71af05";
props["currentPlayerLevel"] = 6;

Kibotu.GetPersonalizedBanner(props, asset =>
{
    if (asset != null && !asset.IsControlGroup)
    {
        string imageUrl = asset.imageFullUrl;
        // This is the personalized banner
        // You can now use imageUrl as needed
    }
    else
    {
        // Control group
        // Apply your regular handling for this case
    }
});
```

### Dummy response

During the integration phase, `debugForceImageUrl` property can be utilized to obtain a static placeholder image. This feature forces the system to return the specified image URL from Kibotu processor. This is useful for testing the integration before there are any approved assets in your account.

```
props["debugForceImageUrl"] = "https://dummyimage.com/900x520/000/fff.png&text=Hello+from+Kibotu";
```

Remove this feature from the production code once the integration is complete, to ensure the system functions with actual assets.


# Quests

Lists all functions and model classes used within the SDK to support client-side quest functionality in Unity.

## Functions and Methods

### InitQuests

Initializes the local state of quests functionality. Should be called after player ID is available.&#x20;

```
var paramsForQuestsPersonalization = new Dictionary<string, object>
{
    // Optional params go here
};
Kibotu.InitQuests(paramsForQuestsPersonalization);
```

### TriggerQuestState

Handles the triggered event, which could involve progressing an active quest or starting a new one.

```
var paramsForQuestsPersonalization = new Dictionary<string, object>
{
    // Optional params go here
};
Kibotu.TriggerQuestState("GameWin", paramsForQuestsPersonalization);
```

### TriggetQuestUI

Manages the visual communication of the quest's state to the player. If it returns true, then there is new information to be shown to the player.

```
var paramsForQuestsPersonalization = new Dictionary<string, object>
{
    // Optional params go here
};
if (Kibotu.TriggerQuestUI("Main_AutoShowPopup", paramsForQuestsPersonalization))
{
    QuestModal.ShowPopup(Kibotu.GetActiveQuest());
}
```

### GetActiveQuest

Returns a [KibotuQuest object](#kibotuquest) that contains comprehensive data to be communicated to the player.

### onQuestRewardAction

To be executed when the player acknowledges that they won the quest.

```
Kibotu.onQuestRewardAction(currentQuest.Id);
```

### KibotuQuest.GetPrize

Returns a string that is the prize identifier when the player wins it.

### KibotuQuestGraphics.GetGraphic

Returns [KibotuQuestGraphic](#kibotuquestgraphic) based on the quest's state.

```
var graphic = quest.Graphics.GetGraphic(currentQuest.Progress.Status);
await mainImage.SetImageAsync(graphic.Background);
await topBannerImage.SetImageAsync(graphic.TitleImage);
```

## Models

### KibotuQuest

```
public string Id;
public string Title;
public string Enabled;
[CanBeNull] public KibotuQuestProgress Progress;
public KibotuQuestProgressMilestone[] Milestones;
public List<string> CountryCodes;
public KibotuQuestGraphics Graphics;
public KibotuQuestTriggers Triggers;
public string CollectibleIconImage;

public int TotalSteps;
public JObject TargetFilter;
public DateTime from;
public DateTime to;
```

### KibotuQuestProgress

```
public string CurrentState;
public int CurrentStep = 0;
public EnumQuestStates Status;

public enum EnumQuestStates
{
    Welcome,
    Progress,
    Won,
    Lost
}
```

### KibotuQuestProgressMilestone

```
public int Order;
public string PrizeTitle;
public string PrizeImage;
public string PrizeSku;
public int Goal;
public string GoalImage;
```

### KibotuQuestGraphics

```
public KibotuQuestGraphic Welcome;
public KibotuQuestGraphic Progress;
public KibotuQuestGraphic Lost;
public KibotuQuestGraphic Won;
```

### KibotuQuestGraphic

```
public string Background;
public string TitleImage;
```

### KibotuQuestTriggers

```
public KibotuQuestTriggerEvents State;
public KibotuQuestTriggerEvents UI;
```

### KibotuQuestTriggerEvents

```
public List<KibotuQuestEvent> Welcome;
public List<KibotuQuestEvent> Progress;
public List<KibotuQuestEvent> Finish;
```

### KibotuQuestEvent

```
public string EventName;
public string EventValue;
```