Introduction

The Platform API allows you to access and manipulate the configuration of your game, without the need to use the deltaDNA user interface. One of the more common use cases for this is to set up a new game with the same events and parameters of an existing game, and that’s what we’ll be going through in this tutorial.

This tutorial assumes you’re already familiar with using APIs and can authenticate a key to get a token.

1. Configuration

For this tutorial we’re assuming that you have one key with access to all the environments you need. You can see an introduction to that elsewhere in the documentation.

In the example we’re creating, we’ll need the following configuration pieces.

Configuration item sample value description
GlobalKey 68c0ca9a-1234-abcd-4321-271e00815357 Corresponds to your API key
GlobalPassword The password for your API key
GlobalSourceEnv 8755 The environment ID you’re drawing events and parameters from
GlobalTargetApp 16992 The application ID you’re sending parameters to
GlobalTargetEnvironment 16993 The application ID you’re sending events to

2. Retrieve application and environment IDs

Using the endpoint https://api.deltadna.net/api/engage/v1/environments/ you can get a list of the IDs of all applications and environments your key has access to. Here is a piece of sample output for a key that has access to our demonstration environment “DeltaSlot” and an empty game I created or the purposes of copying to.

We can see that each environment has an ID, but what’s not provided is an application ID.

For clarity, when you create a game, that game has one application ID that applies to the game as a whole, and two environment IDs that applies to the Dev and Live contexts within that game.

The Dev environment ID is always the application ID +1, and the Live environment ID is always the application ID +2. As such we can infer the DeltaSlot applicaiton ID is 8754 and the DeltaSlot-Shadow application is 16992

In this tutorial, we’ll be copying all events from the Live DeltaSlot environment straight into the Dev environment for DeltaSlot-Shadow.

3. Identify existing parameters

Many of the parameters that exist in the deltaDNA platform are created at the same time the game is created. Since there will be situations when these default parameters are needed in our custom events, it’s important to have their IDs cached.

Another important thing to be aware of is that parameters exist at the application level. A change to a parameter (not an event) affects both the Live and Dev environments, so endpoints that involve their creation will require the application ID, not an environment ID.

Our endpoint is: https://api.deltadna.net/api/events/v1/event-parameters?applicationId=16992 And this will give us a filtered list of parameters, each of which has two important pieces of information that will be needed for step 5. The parameter name, and the parameter ID. we’re going to cache these into a key value pair.

3. Copy parameters across

We’re now in a place where we’re able to copy all existing parameters across to the new environment. As we do that, we’ll update the cache of key value pairs with new names and their corresponding IDs.

We can use the same technique as above to retrieve one page at a time of parameters from the first game. As we iterate through each page, we’ll try and create the parameter in the destination. We’re going to get a lot of failures due to the default parameters already existing, so we need to be prepared for those responses.

 

The structure above is very similar to how we get and cached the existing parameters, but it targets the source application instead, and performs two operations on a parameter it finds.

First, it tries to run the addParameter function, second it tries to update the cache.

Copying the parameter

Parameters are relatively complex objects, but they can be repackaged quite easily. The only difference between the JSON for a parameter that we’ve retrieved using the API, and the JSON we’ll send to create the new one is the application ID.

What we’ll do take that existing parameter object, transform it with a new application ID and send it to the platform API. What we’ll get back will inform what we do next.

If we get a 2XX response code the we know that everything’s gone ahead correctly and the parameter has been copied across. Alternatively if we get a 400 bad request, then high probability that a parameter sharing the same name already exists in the target application.

If it already exists, then our initial seeding of the cache will already have it recorded.

Updating our cache

Having a complete list of parameters, new and old, in the target environment is how we can successfully add parameters into the events we’re creating in the target game.

This implementation uses null values ( None in Python) to distinguish between an event or parameter that could not be created, and one that could.

If we receive a None into our cache updating method, that’s our indicator not to update.

4. Copy events and link parameters

WE can use the events endpoint to get a list of all the events in our source environment. The nice thing about pulling an event in this way is that it includes all the associated parameters. This means from a design perspective it’s most convenient to create our empty events in the target environment, and then immeidately link the parameters to it.

Thanks to our complete cache of parameter IDs in the target application, we’ve everything we need to do this at this point in the process.

This is the most complex piece of code in this tutorial, so I will break it down into three segments

Set up and fetch events

Add the event to the target environment

Events don’t have much in the way of detail and are fairly easy to construct. All they need is a name, and a description. We send that with a specific target environment in mind and the event is added.

The more significant distinctions between your events tends to be in which parameters are associated with it. That’s defined in the linking section below.

Link parameters

The association of parameters to an event comes down to two IDs, the ID of the parameter and the ID of the event. For each source event, you’ll need to go through its parameters and add them on to the target event in the new environment.

It’s most convenient to do this just after creating the event in the target environment, as we already have the information to hand.

5. Check the results

And that’s it. Let the script run its course, you’ll find that all existing events and parameters are copied over to your new game. Remember that whilst you can make changes to the parameters in your event schema, you can’t change the parameter name or data type after we receive data for it.

Be sure to give everything a thorough check-over before continuing!

Contact Us

We're not around right now. But you can send us an email and we'll get back to you, asap.