About recommendation system🔗

A recommendation system is a machine learning tool which shows the most relevant product to the user. The system allows you to solve various business tasks: increase the number of sales, conversion, average check, retention, LTV and other indicators of the game project.

Depending on the set of recommended items and target audience, the recommendation system can:

• select personal offers and bundles
• show recommended items without discount to increase sales of non-promotional items
• customize the game store by relevance for each user
• create a balance between showing ads and selling items depending on the player's profile
• counteract the churn of players by selecting the best offer or gift at the right time.

Algorithm for working with the RecSys team🔗

Steps🔗

1. Formalization of a business task.
2. Testing different models and choosing the best one.
3. Conducting an A/B test of the model.
4. Assessment of economic efficiency.
5. Launching in Production.
6. Support and monitoring after integration.

What will be needed from the project🔗

1. Initiation meeting: choice of a task, target audience, business metrics.
2. Formation of a list of items for recommendations. If necessary, the establishment of items in the payment system.
3. Integration of the API of the recommendation system.
4. Consulting on game logs and mechanics.
5. In some cases, it is required to add logging of some events (for example, showing and buying an offer).

Data🔗

Game logs🔗

Game logs are used to create recommendations. They are stored in the game DWH.

Game logs are converted by the RecSys team into a unified data format needed for the recommendation platform.

Basically, the following game events are used:

• Log of spending/receiving game currency
• Log of adding/removing an item from inventory
• Log of the passage of the tutorial
• Log of getting level
• Battle log
• Log of showing an offer/item from the recommendation system
• Log of click on the offer of the recommendation system
• Log of the purchase of the offer of the recommendation system
• Login/logout log
• Log of registration in the game
• Purchase log

Items🔗

You need to decide on the list of subjects available for the recommendation system.

Two scenarios are possible:

1. The project determines the list of subjects available to the recommendation system.
2. The RecSys team conducts research and selects a set of items or suggests a set of generated items (bundles or basic items with slightly changed characteristics).

Collecting data🔗

In some cases, when new items are launched or items were previously shown to a specific audience and the historical logs cannot be used to solve the current task, the items are shown randomly in order to collect enough statistics. Usually this period takes from 1 to 3 weeks and is carried out through the standard scheme of integration with the project.

Testing🔗

Testing functionality🔗

Functional testing can be divided into several parts:

1. Testing the response on user recommendations from the RecSys API - on the project side. Basic approach: RecSys team sets up user IDs and recommendations in the test or production API. The items can be random or they can cover specific use cases. The project asks for recommendations and validates the responses.
2. Testing how the offers are shown in the game - on the project side. RecSys checks the logging of impressions and purchases.
3. A/B tests, models - on the side of the RecSys team.

A/B🔗

The division of users into groups for A/B testing is carried out on the RecSys side. The mechanism of A/B tests allows you to roll out an experiment to a different audience size and flexibly restart experiments, as well as conduct several experiments at the same time. All breakdown data is stored in historical tables, which makes it easy to reproduce the results if necessary. All decisions on the implementation of the recommendation system are made by calculating the results of an A/B test and observing statistically significant changes.

Integration🔗

Getting user recommendations🔗

GET /projects/{project_id}/user/{user_id}/recommendations

Request parameters:

Example of request and response:

Request

GET /projects/test/user/1605632/recommendations

Response

200 OK

{
  "items:": [
    {
      "id": "123",
      "is_mrgs_show": true,
      "is_transaction": false,
      "images": {
          "landscape" : {
              "img_2400" : "https://localhost/image%20test_2400.png",
              "img_800" : "https://localhost/image%20test_800.png",
              "hash_2400" : "abcdefghigklmnopqrstuvwxyz123456",
              "hash_800" : "abcdefghigklmnopqrstuvwxyz123456"
          },
          "portrait" : {
              "img_2400" : "https://localhost/image%20test_2400.png",
              "img_800" : "https://localhost/image%20test_800.png",
              "hash_2400" : "abcdefghigklmnopqrstuvwxyz123456",
              "hash_800" : "abcdefghigklmnopqrstuvwxyz123456"
          }
      }
        }
  ]
}

Authorization🔗

To make requests for API recommendations, you need basic authorization for the project or studio. Without authorization, the API will respond to all requests with 422 errors.

To log in, you need to add a user and password to the request, which are sent to the project by the developers of the recommendation system. For test and production API, username and password may be different.

API Addresses🔗

The game server accesses the recommendation system production or test API.

Production API: https://recsys.my.games

QA API: https://api-test.recsys.pvt

Error format🔗

General response format for 422 errors:

Response

HTTP/1.1 422 Unprocessable Entity for url: https://api-test.recsys.pvt/projects/test/user/105240266041/recommendations/feature/0 
Connection: keep-alive
Content-Length: 180
Content-Type: application/json
Keep-Alive: 5

{
  "code": "recommendation_not_found",
  "text": "Recommendation for 105240266041 not found",
  "context": {
    "user_id": "105240266041"
  }
}

In case of an unexpected error, a response with a 500 status will be returned.

Client integration🔗

To send required events, you need to use the MRGSRecommendations class in the MRGS module of the same name. All event objects can be created through the MRGSRecSysEvent factory, or through the standard constructor of the class responsible for the event.

Examples of sending events:

// Log of spending/receiving game currency
var currencyChangeEvent = MRGSRecSysEvent.CurrencyChange("item_id", "transaction_id", 123.4f, "gold");
// Event sending
MRGSRecommendations.Instance.TrackEvent(currencyChangeEvent);

// Log of adding/removing an item from inventory
MRGSRecommendations.Instance.TrackEvent(MRGSRecSysEvent.InventoryChange("item_id", -123));

// Log of getting level
MRGSRecommendations.Instance.TrackEvent(MRGSRecSysEvent.LevelGain(555));

// Battle log
MRGSRecommendations.Instance.TrackEvent(MRGSRecSysEvent.PlayMatch("start", "win"));

// Log of showing/click/purchase of the offer of the recommendation system
MRGSRecommendations.Instance.TrackEvent(MRGSRecSysEvent.OfferAction("some_offer_id", MRGSRecSysEvent.ActionTypeView));
MRGSRecommendations.Instance.TrackEvent(MRGSRecSysEvent.OfferAction("some_offer_id", MRGSRecSysEvent.ActionTypeClick));
MRGSRecommendations.Instance.TrackEvent(MRGSRecSysEvent.OfferAction("some_offer_id", MRGSRecSysEvent.ActionTypePurchase));

// Log of spending/receiving game currency
MRGSRecSysEvent* ev = [MRGSRecSysEvent currencyChangeWithObjectId:@"item_id" transactionId:@"transaction_id" amount:123.4f currency:@"gold"];
// Event sending
[[MRGSRecommendations sharedInstance] trackEvent:ev];

// Log of adding/removing an item from inventory
[[MRGSRecommendations sharedInstance] trackEvent:[MRGSRecSysEvent inventoryChangeWithObjectId:@"item_id" count:-123]];

// Log of getting level
[[MRGSRecommendations sharedInstance] trackEvent:[MRGSRecSysEvent levelGain:555]];

// Battle log
[[MRGSRecommendations sharedInstance] trackEvent:[MRGSRecSysEvent playMatchWithStage:@"start" result:@"win"]];

// Log of showing/click/purchase of the offer of the recommendation system
[[MRGSRecommendations sharedInstance] trackEvent:[MRGSRecSysEvent offerActionWithOfferId:@"some_offer_id" actionType:kMRGSRecSysOfferActionView]];
[[MRGSRecommendations sharedInstance] trackEvent:[MRGSRecSysEvent offerActionWithOfferId:@"some_offer_id" actionType:kMRGSRecSysOfferActionClick]];
[[MRGSRecommendations sharedInstance] trackEvent:[MRGSRecSysEvent offerActionWithOfferId:@"some_offer_id" actionType:kMRGSRecSysOfferActionPurchase]];

import games.my.mrgs.recsys.MRGSRecSysEvent;
import games.my.mrgs.recsys.MRGSRecSysEvents;
import games.my.mrgs.recsys.MRGSRecommendations;

// Log of spending/receiving game currency
final MRGSRecSysEvent currencyChangeEvent = new MRGSRecSysEvents.CurrencyChangeEvent("item_id", "transaction_id", 123.4f, "gold");
// Event sending
MRGSRecommendations.getInstance().trackEvent(currencyChangeEvent);

// Log of adding/removing an item from inventory
MRGSRecommendations.getInstance().trackEvent(new MRGSRecSysEvents.InventoryChangeEvent("item_id", -123));

// Log of getting level
MRGSRecommendations.getInstance().trackEvent(new MRGSRecSysEvents.LevelGainEvent(555));

// Battle log
MRGSRecommendations.getInstance().trackEvent(new MRGSRecSysEvents.PlayMatchEvent("start", "win"));

// Log of showing/click/purchase of the offer of the recommendation system
MRGSRecommendations.getInstance().trackEvent(new MRGSRecSysEvents.OfferActionEvent("some_offer_id", MRGSRecSysEvent.ACTION_TYPE_VIEW));
MRGSRecommendations.getInstance().trackEvent(new MRGSRecSysEvents.OfferActionEvent("some_offer_id", MRGSRecSysEvent.ACTION_TYPE_CLICK));
MRGSRecommendations.getInstance().trackEvent(new MRGSRecSysEvents.OfferActionEvent("some_offer_id", MRGSRecSysEvent.ACTION_TYPE_PURCHASE));

Extra event params🔗

Since MRGS 6.4.0 version, you can add extra params to events. You can add fields from unified logs such as customString1-20, level, customFloat and others.

var ev = MRGSRecSysEvent.LevelGain(555);
ev.AddCustomParams(new Dictionary<string, object>()
{
    {"test_param_1", "testStr"},
    {"customFloat_1", 123.456f},
});
MRGSRecommendations.Instance.TrackEvent.TrackEvent(ev);

MRGSRecSysEvent* event = [MRGSRecSysEvent levelGain:555];
[event addCustomParams:@{
    @"test_param_1": @"testStr",
    @"customFloat_1" : @(123.456f)
}];
[[MRGSRecommendations sharedInstance] trackEvent:event];

import games.my.mrgs.recsys.MRGSRecommendations;
import games.my.mrgs.recsys.MRGSRecSysEvent;
import games.my.mrgs.recsys.MRGSRecSysEvents;

final MRGSRecSysEvent event = MRGSRecSysEvents.LevelGainEvent(555);
event.putParam("test_param_1", "testStr");
event.putParam("customFloat_1", 123.456f);
MRGSRecommendations.getInstance().trackEvent(event);