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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
[ { "game": "DeltaSlot", "id": 8755, "name": "Dev" }, { "game": "DeltaSlot", "id": 8756, "name": "Live" }, { "game": "DeltaSlot-Shadow", "id": 16993, "name": "Dev" }, { "game": "DeltaSlot-Shadow", "id": 16994, "name": "Live" } ] |
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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
def seedParametersToCache(): global GlobalParams #a dictionary of key-value pairs global GlobalTargetApp #the ID of our target game. oldJSON = [] params = "" page = 0 while params != oldJSON: oldJSON = params page = page + 1 #fetch a new page of events url = 'https://api.deltadna.net/api/events/v1/event-parameters?applicationId=%s&limit=100&page=%s' % (GlobalTargetApp,page) headers = {'Authorization' : 'Bearer %s' % GlobalToken} response = requests.get(url = url, headers=headers) params = json.loads(response.content) #fetch from target ID for parameter in params: if parameter["application"] == GlobalTargetApp: #redundant GlobalParams[parameter["name"]] = parameter["id"] |
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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
def copyParameters(sourceApp,targetApp): token = getToken() page = 0 responseJSON = '' oldResponse = '' url = "https://api.deltadna.net/api/events/v1/event-parameters?limit=100&page=%s&applicationId=%s" % (page,GlobalSourceEnv) headers = {'Authorization' : 'Bearer %s' % token} response = requests.get(url = url, headers=headers) responseJSON = json.loads(response.text) #if our last iteration contained unfamiliar parameters, do the following. while responseJSON != oldResponse: for parameterObj in responseJSON: if parameterObj['application'] == sourceApp: #redundant filtering #this is a parameter in the source application that we wish to copy. #Therefore, try and add it to the target application (will fail if it's a default parameter) newParamID = addParameter(parameterObj,GlobalTargetApp) addParameterToCache(parameterObj["name"],newParamID) |
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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
def addParameter(json, application): #set the Application ID to be the target game. json["application"]= application token = getToken() url = "https://api.deltadna.net/api/events/v1/event-parameters/" headers = {'Authorization' : 'Bearer %s' % token} response = requests.post(url=url, json=json, headers=headers) if response.status_code != 200: return None #if the parameter already exists, we will not receive a 200 response code. #we should not attempt to update the cache in that event. else: responseJSON = json.loads(response.text) paramID = responseJSON["id"] return paramID return response |
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.
|
1 2 3 4 |
def addParameterToCache(ParameterName, parameterID): global GlobalParams if parameterID is not None: GlobalParams["ParameterName"] = parameterID |
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
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 |
def copyEventsAndParameters(sourceEnv, targetApp): global GlobalSourceEnv global GlobalTargetEnvironment global GlobalFlagUpdateExistingEvents token = getToken() seedParametersToCache() #set up for iterating page = 0 responseJSON = '' oldResponse = {} #if our last iteration contained unfamiliar events, do the following. while responseJSON != oldResponse: #update the comparison events for next loop oldResponse = responseJSON page = page + 1 #fetch a new page of events url = "https://api.deltadna.net/api/events/v1/events?limit=10&page=%s&environmentId=%s" % (page,GlobalSourceEnv) headers = {'Authorization' : 'Bearer %s' % token} response = requests.get(url = url, headers=headers) responseJSON = json.loads(response.text) #begin loop of events for event in responseJSON: if event['environment'] == GlobalSourceEnv: #redundant validation, the API should be filtered already. #copy the event to the target application. If we get a None repsonse, then the copy failed. newEventID = addEvent(event,targetApp) if newEventID is not None: #copy parameters one by one, getting parameter IDs into a list. for parameterObj in event['parameters']: #get the ID if the parameter already exists. May return a blank. linkparamID = getParameterFromCache(parameterObj["name"]) linkParameter(linkparamID,newEventID,parameterObj["required"]) |
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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
def addEvent (eventObj, targetApp): token = getToken() newEvent = { "environment":targetApp+1, #target's the Dev environment of our target application "name": eventObj["name"], "description":eventObj["description"], } url = "https://api.deltadna.net/api/events/v1/events" headers = {'Authorization' : 'Bearer %s' % token} response = requests.post(url = url, headers=headers, json=newEvent) if response.status_code != 200: return None #if the already exists, we will not receive a 200 response code, and the code should not attempt to synchronise parameters. else: responseJSON = json.loads(response.text) eventID = responseJSON["id"] return eventID |
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.
|
1 2 3 4 5 6 |
# with a parameter ID and event ID in the same environment, link the parameter to the event, and maybe flag it as required. def linkParameter(parameterID,eventID,required): token = getToken() url = 'https://api.deltadna.net/api/events/v1/events/%s/add/%s' % (eventID,parameterID) headers = {'Authorization' : 'Bearer %s' % GlobalToken}# response = requests.get(url = url, headers=headers) |
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!
