Playgen: API Integration

Playgen: API Overview

Playgen is the AI-driven platform for taking your mobile games from seed to scale. Playgen automates asset generation, economy balancing, and experience personalization, enabling fast iteration loops and autopilot growth.

Metagen is a live personalized experience optimization engine. It eliminates the need to manually design, adjust, test, and segment player progression and offers. Metagen enables game developers to stop wasting cycles on finding arbitrary numbers and focus instead on perfecting the core experience.

Optimization in Metagen is done in real-time using live player behavior, while user segments are discovered and handled organically, to find just the right experience parameters for each and every player.

Metagen API Integration

This quick start guide provides a brief overview of the steps required to use the Playgen API for optimizing player experience in your game.

Flow at a Glance

We want to register players, get a personalized experience for each, then update the system on their performance:

Register Players: Use POST projects/:project_id/players to create player accounts in Playgen.
Get Personalized Experience: Use GET projects/:project_id/players/:player_id to retrieve the player’s personalized experience.
Update Player Performance: Use POST projects/:project_id/actions to sync player actions, or PUT projects/:project_id/players/:player_id to directly update the player’s performance profile.

That’s it!

Authentication

Every request to the Metagen API requires the project’s API key and secret. These should be included in the headers of each request: X-API-Key and X-API-Secret.

Error Handling

Successful requests will always include a JSON status field with a '2xx` value. If any error occurs, the Playgen API will respond with the appropriate HTTP error status code and provide details in JSON format. For example:

{
	"status": "unprocessable_entity",
	"error": {
		"message": "Name is too short (minimum is 3 characters)"
	}
}

Creating a Player

Use this route to create a new Playgen player account. The response will include the player’s personalized experience parameters.

Endpoint: POST /api/v1/projects/:project_id/players

Example Request:

curl -X POST https://playgen.gg/api/v1/projects/:project_id/players \
	-H "Content-Type: application/json" \
	-H "X-API-Key: {your_api_key}" \
	-H "X-API-Secret: {your_api_secret}" \
	-d '{
		"player": {
			"external_id": "{player_id_in_your_system}",
			"profile": {
				"name": "LoudJetpack37",
				"vip_level": 15
			}
		}
	}'

Example Response:

{
	"status": 200,
	"player": {
		"id": "ff8e889e-22d4-4882-9276-0f6e65393b9b",
		"external_id": "{player_id_in_your_system}",
		"created_at": "2024-06-25T20:16:21.257Z",
		"updated_at": "2024-06-25T20:16:21.257Z",
		"project_id": "{your_project_id}",
		"profile": {
			"name": "LoudJetpack37",
			"vip_level": 15
		},
		"metrics": {},
		"experiences": {
			"test_experiment": {
				"id": 3482,
				"experiment_id": 17,
				"branch_id": 819,
				"score": 0.0,
				"duration": 0,
				"num_sessions": 0,
				"metrics": {},
				"settings": {
					"x": 1.2494412269036566,
					"y": 0.6545238145310833
				}
			}
		}
	}
}

Retrieving a Player

Use this route to get data about an existing player, including the player’s personalized experience parameters.

Endpoint: GET /api/v1/projects/:project_id/players/:player_id

Example Request:

curl -X GET https://playgen.gg/api/v1/projects/:project_id/players/:player_id \
	-H "Content-Type: application/json" \
	-H "X-API-Key: {your_api_key}" \
	-H "X-API-Secret: {your_api_secret}" \

Example Response:

{
	"status": 200,
	"player": {
		"id": "ff8e889e-22d4-4882-9276-0f6e65393b9b",
		"external_id": "{player_id_in_your_system}",
		"created_at": "2024-06-25T20:16:21.257Z",
		"updated_at": "2024-06-25T20:16:21.257Z",
		"project_id": "{your_project_id}",
		"profile": {
			"name": "LoudJetpack37",
			"vip_level": 15
		},
		"metrics": {},
		"experiences": {
			"test_experiment": {
				"id": 3482,
				"experiment_id": 17,
				"branch_id": 819,
				"score": 0.0,
				"duration": 0,
				"num_sessions": 0,
				"metrics": {},
				"settings": {
					"x": 1.2494412269036566,
					"y": 0.6545238145310833
				}
			}
		}
	}
}

Updating a Player

Use this route to update information about an existing player, including information about the player’s current experience performance.

Endpoint: PUT /api/v1/projects/:project_id/players/:player_id

Example Request:

curl -X PUT https://playgen.gg/api/v1/projects/:project_id/players/:player_id \
	-H "Content-Type: application/json"
	-H "X-API-Key: your_api_key"
	-H "X-API-Secret: your_api_secret"
	-d '{
		"player": {
			"profile": {
				"name": "LoudJetpack37",
				"vip_level": 15
			},
			"metrics": {
				"IAP": 10,
				"RV": 5,
				"sessions": 113,
				"playtime": 1150
			}
		}
	}'

Example Response:

{
	"status": 200,
	"player": {
		"id": "ff8e889e-22d4-4882-9276-0f6e65393b9b",
		"external_id": "{player_id_in_your_system}",
		"created_at": "2024-06-25T20:16:21.257Z",
		"updated_at": "2024-06-25T20:16:21.257Z",
		"project_id": "{your_project_id}",
		"profile": {
			"name": "LoudJetpack37",
			"vip_level": 15
		},
		"metrics": {
			"IAP": 10,
			"RV": 5,
			"sessions": 113,
			"playtime": 1150
		},
		"experiences": {
			"test_experiment": {
				"id": 3482,
				"experiment_id": 17,
				"branch_id": 819,
				"score": 0.0,
				"duration": 0,
				"num_sessions": 0,
				"metrics": {},
				"settings": {
					"x": 1.2494412269036566,
					"y": 0.6545238145310833
				}
			}
		}
	}
}

Creating an Action

Use this route to sync player actions, activities, and events to Playgen.

Endpoint: POST /api/v1/projects/:project_id/actions

Example Request:

curl -X POST https://playgen.gg/api/v1/projects/:project_id/actions \
	-H "Content-Type: application/json" \
	-H "X-API-Key: your_api_key" \
	-H "X-API-Secret: your_api_secret" \
	-d '{
		"player_id": "{playgen_player_id}",
		"project_id": "{your_project_id}",
		"activity": {
			"name": "deposit",
			"data": {
				"amount": 6,
				"currency": "USD"
			}
		}
	}'

Example Response:

{
	"status": 200,
	"action": {
		"id": "9e7925e7-04fa-4392-8e12-3a3c7ec24443",
		"created_at": "2024-06-25T19:33:27.911Z",
		"updated_at": "2024-06-25T19:33:27.911Z",
		"player_id": "{player_id}",
		"project_id": "{your_project_id}",
		"name": "deposit",
		"data": {
			"amount": 6,
			"currency": "USD"
		}
	}
}

Questions

What happens if your platform is down?

Worst case: the player experience will be a bit behind the iterative optimization process until connection is re-established, while service operations will be unharmed or gracefully downgraded.

While our SDKs offer automatic smart caching on the client-side, direct integration with the Playgen API will require you to develop your own failsafe caching mechanism. We suggest the following integration guardrails:

Use a short timeout and an exponential backoff retry mechanism for API requests.
Use the default values from the game’s schema, in case a request for a personalized player experience fails,
Further personalized caching can be added per-player or per-branch, with requests for fresh data sent to the Playgen API only once in a while.

Is there an SDK we can directly integrate with, instead?

Yes, the Playgen Unity SDK provides an easy-to-use wrapper to all API endpoints, offering a more fully-featured and streamlined experience and a much simpler integration process.