At this time, the GameMaker SDK is not actively supported. Basic functionality does work however there may be gaps in more complex parts of the SDK.

Introduction

The deltaDNA SDK for GameMaker allows your GameMaker games to send information on in-game events and player actions to the deltaDNA platform.
Events are sent to the deltaDNA platform as JSON objects, these events are managed and tracked using the online dashboard.
When your game triggers events the SDK will store them locally and Upload them at regular intervals when a connection is available, or at a time of your choosing. This allows the SDK to collect events regardless of connectivity and gives you control over the timing and frequency of uploads.
Events vary in complexity, but are all derived from a common event schema. This document and the accompanying example application provide examples of increasingly complex events.
NB: The deltaDNA SDK requires at least the “Standard” version of GameMaker to function. HTTP Requests and JSON Encoding functions used by the deltaDNA SDK are not supported in the “FREE” version.

Download deltaDNA SDK version v0.1 for GameMaker:

Download and Unzip the deltaDNA GameMaker SDK v0.1.
There is also an example project that you can download.
Copy the SDK scripts to your GameMaker project’s Scripts folder

Initialise the SDK

Before you can send events to the deltaDNA platform you need to initialise the SDK with the following paramaters.

environmentKey This is a unique 32 character string assigned to your application. You will be assigned separate application keys for development and production builds of your game.
collectURL This is the address of the server that will be collecting your events.
engageURL This is the address of the server that will provide real-time A/B Testing and Targeting. This is only required if your game uses these features.
userID Every user needs to have a unique userID. If your game can provide a unique userID you can use it. Alternatively, the platform can generate a unique User Id and use it for all subsequent events. To generate a unique userID, call the scr_deltaDNA_generateUUId() function and initialise the SDK with the String value it returns.
hashsecret is a secret hash value that can be used to protect your events from modification during communications. If enabled you will find the secret hash value on your Game Details page as pictured below. If you are not using hashing you should initialise the SDK with the hash secret set to "no_hashing"
fileStoreSize is an integer value containing the maximum size in bytes of file storage for events, or 0 if no storage should be used.
fileStorePath is a String containing the path from working directory to a file where events should be stored if no net connection is available.
attemptLimit is the maximum number of attempts at event submission before event should be discarded.

These parameters can be found on your game details page. Please note, there are different environmentKey parameters for your DEV & LIVE environments, you will need to change the environment key that you initialise the SDK with as you move from development and testing to production.

game details page

For the purposes of this demonstration we have added the initialisation code to the creation of the first room.

The code to initialise the SDK should look something like :

globalvar dd_engagement_request_id;
globalvar dd_engagement_request_result;
dd_engagement_request_result = "no engagement request yet";
dd_engagement_request_id = -1;

randomize();

var user_id = scr_deltaDNA_generateUUId();
if os_browser == browser_not_a_browser {
    // get user id from file if exists
    ini_open("dd_config.ini");
    
    if ini_key_exists("user","userId") {
        user_id = ini_read_string("user","userId",user_id);
    } else {
        ini_write_string("user","userId",user_id);
    }
    ini_close();
}

scr_deltaDNA_initialize("<Your Environment Key>",
                        "http://<Your Collect URL>/collect/api",
                        "http://<Your Engage URL>",
                        user_id,
                        "no_hashing",
                        2048,
                        "ddEventStorage",
                        2);

globalvar dd_engagement_request_id;

globalvar dd_engagement_request_result;

dd_engagement_request_result = "no engagement request yet";

dd_engagement_request_id = -1;

randomize();

var user_id = scr_deltaDNA_generateUUId();

if os_browser == browser_not_a_browser {

// get user id from file if exists

ini_open("dd_config.ini");

if ini_key_exists("user","userId") {

user_id = ini_read_string("user","userId",user_id);

} else {

ini_write_string("user","userId",user_id);

}

ini_close();

}

scr_deltaDNA_initialize("<Your Environment Key>",

"http://<Your Collect URL>/collect/api",

"http://<Your Engage URL>",

user_id,

"no_hashing",

2048,

"ddEventStorage",

2);

The initialise function sets up various global variables required by the SDK, it will return 0 if successful, any other value indicates a failure.

Add SDK Control Objects

You will need to add an object to your game to control event uploading and handle the responses from deltaDNA

Upload Controller
The upload controller will periodically call Upload Events in order to upload your event to deltaDNA. This should be reasonably frequent to ensure that events are not lost, or delayed if a user closes their session unexpectedly.
Response Controller
The response controller should listen for HTTP Responses and call Process Collect Response in order to delete cached events after a successful upload, or flag them for retry is unsuccessful.

UploadController

The object we add to our room contains 3 actions

The Create event sets the font to fnt_announce, the colour to black and an alarm to trigger in 1800 steps.

When alarm triggers it resets itself to trigger again in another 1800 steps and executes a script to upload any cached events

dd_announce = "upload timer ticked over";
scr_deltaDNA_uploadEvents();

1 2	dd_announce = "upload timer ticked over"; scr_deltaDNA_uploadEvents();

The final HTTP action listens for a response from event upload HTTP Post and executes a script when the response is received.

the script is called scr_deltaDNA_processCollectResponses

We are now ready to start recording events and sending them to the deltaDNA platform, but before we do, let’s take a quick look at what an event looks like.

Anatomy of an event

All events are recorded as JSON documents with a shared basic schema . The document will be different for every event type, but all of them should adhere to the following minimal schema:

{
   "eventName":"gameEnded",
   "userID":"a2e92bdd-f59d-498f-9385-2ae6ada432e3",
   "sessionID":"0bc56224-8939-4639-b5ba-197f84dad4f4",
   "eventTimestamp":"2014-07-04 11:09:42.491",
   "eventParams":{
      "sdkVersion":"GameMaker SDK v0.1",
      "platform":"WEB"
   }
}

{

"eventName":"gameEnded",

"userID":"a2e92bdd-f59d-498f-9385-2ae6ada432e3",

"sessionID":"0bc56224-8939-4639-b5ba-197f84dad4f4",

"eventTimestamp":"2014-07-04 11:09:42.491",

"eventParams":{

"sdkVersion":"GameMaker SDK v0.1",

"platform":"WEB"

}

The GameMaker SDK will automatically populate the userID, sessionID, eventTimestamp , platform & sdkVersion parameters for every event you send. When you add parameters to an event they will all be placed inside the eventParams object.
The order of the parameters in your JSON event doesn’t matter.

You can inspect the parameters that each event expects, their type and any formatting or enumeration rules in the Event Manager.

Parameters can be either Optional or Required. Any parameters that are optional don’t have to be included in your event if you don’t have a valid value to put in them. It is better to leave them out completely, than set their value to null or empty.
This basic event structure provides great flexibility for recording events with varying levels of complexity, from simple events like the one above to complex events containing nested arrays. The following code examples will show a variety of events from simple to complex.
Please note that all events are validated and will be rejected if they don’t match the schema in the Event Manager.

Create Events

Once the SDK is initialised and you’ve created your control objects you are ready to create some events.

The following code specifies the name of the event we want to send, “gameStarted” and an empty parameters object then triggers an event. In this example game we have attached a code action to the “Left Click” event of an object,

var gameStartedEventName = "gameStarted";
var gameStartedEventParams = ds_map_create();
scr_deltaDNA_triggerEvent(gameStartedEventName, gameStartedEventParams);

var gameStartedEventName = "gameStarted";

var gameStartedEventParams = ds_map_create();

scr_deltaDNA_triggerEvent(gameStartedEventName, gameStartedEventParams);

That was a pretty simple event, it didn’t even contain any event parameters. Most events will only contain up to a few parameters, but some events can contain more and you can of course add your own parameters.

An event with a couple of parameters might look like.

var optionsEventName = "options";
var optionsEventParams = ds_map_create();

ds_map_add(optionsEventParams, "option","volume");
ds_map_add(optionsEventParams, "action","set to 80");

scr_deltaDNA_triggerEvent(optionsEventName, optionsEventParams);

var optionsEventName = "options";

var optionsEventParams = ds_map_create();

ds_map_add(optionsEventParams, "option","volume");

ds_map_add(optionsEventParams, "action","set to 80");

scr_deltaDNA_triggerEvent(optionsEventName, optionsEventParams);

A complex event like a transaction can be made up of multiple objects, potentially tracking multiple products spent and received in the same transaction.

var eventName = "transaction";
var eventParams = ds_map_create();

var productsSpent = ds_map_create();
var realCurrency = ds_map_create();
ds_map_add(realCurrency, "realCurrencyAmount", 500);
ds_map_add(realCurrency, "realCurrencyType", "GBP");
ds_map_add_map(productsSpent, "realCurrency", realCurrency);
ds_map_add_map(eventParams, "productsSpent", productsSpent);

var productsReceived = ds_map_create();
var items = ds_list_create();
var itemOuter = ds_map_create();
var item = ds_map_create();
ds_map_add(item, "itemAmount", 1);
ds_map_add(item, "itemType", "gem");
ds_map_add(item, "itemName", "diamond");
ds_map_add_map(itemOuter, "item", item);
ds_list_add(items, itemOuter);
var index = ds_list_find_index(items, itemOuter);
ds_list_mark_as_map(items, index);
ds_map_add_list(productsReceived, "items", items);
ds_map_add_map(eventParams, "productsReceived", productsReceived);
ds_map_add(eventParams, "transactionType","PURCHASE");
ds_map_add(eventParams, "transactionName","buy_diamond");

scr_deltaDNA_triggerEvent(eventName, eventParams);

var eventName = "transaction";

var eventParams = ds_map_create();

var productsSpent = ds_map_create();

var realCurrency = ds_map_create();

ds_map_add(realCurrency, "realCurrencyAmount", 500);

ds_map_add(realCurrency, "realCurrencyType", "GBP");

ds_map_add_map(productsSpent, "realCurrency", realCurrency);

ds_map_add_map(eventParams, "productsSpent", productsSpent);

var productsReceived = ds_map_create();

var items = ds_list_create();

var itemOuter = ds_map_create();

var item = ds_map_create();

ds_map_add(item, "itemAmount", 1);

ds_map_add(item, "itemType", "gem");

ds_map_add(item, "itemName", "diamond");

ds_map_add_map(itemOuter, "item", item);

ds_list_add(items, itemOuter);

var index = ds_list_find_index(items, itemOuter);

ds_list_mark_as_map(items, index);

ds_map_add_list(productsReceived, "items", items);

ds_map_add_map(eventParams, "productsReceived", productsReceived);

ds_map_add(eventParams, "transactionType","PURCHASE");

ds_map_add(eventParams, "transactionName","buy_diamond");

scr_deltaDNA_triggerEvent(eventName, eventParams);

Upload events

The SDK will queue events internally and may store them to an internal file system if you specified file storage parameters in the initialisation call, and the platform running the game has local storage capabilities.

You are responsible for uploading events from the SDK to the deltaDNA platform by calling the uploadEvents function scr_deltaDNA_uploadEvents(). You might want to setup a timer to call this function at regular intervals (see the Upload Controller Section Above) or, you may wish to upload events at pre-determined points in your game e.g. when the game has loaded and initialised, when the player is starts or completes a level etc..

Depending on connectivity and local storage capabilities the upload function will:

If a net connection is present: submit any file stored events, events awaiting resubmission and queued events.
If no net connection is present and file storage is turned on, dump queued events to file.
If no net connection is present and file storage is turned off, get rid of stored events.

The upload function will return 1 if successful, any other value indicates a failure.

Shutdown

Finally when your game is finished, you should call the Destroy function scr_deltaDNA_destroy() .

Engage

If you are using Engage A/B Testing and Targeting the process is quite similar to sending events, but it happens immediately, your requests aren’t queued up like events are.

Engage Request
Call Request Engagement at a specific point in your game, known as a decisionPoint and get a response reference backOur engage request is created with the following script.

dd_engagement_request_id = scr_deltaDNA_requestEngagement("myDecisionPoint", ds_map_create());
dd_engagement_request_result = "engagement request id: " + string(dd_engagement_request_id);
show_debug_message("Set engagement request result: " + dd_engagement_request_result);

dd_engagement_request_id = scr_deltaDNA_requestEngagement("myDecisionPoint", ds_map_create());

dd_engagement_request_result = "engagement request id: " + string(dd_engagement_request_id);

show_debug_message("Set engagement request result: " + dd_engagement_request_result);

In the example app it is added as an action on the Left Pressed event of a button object in our room.

Engage Response
Add an HTTP listener that calls Process Engagement response with the response reference as the call argument, and get back a map of response data.

show_debug_message("Engagement info obj: executing http event code");
if dd_engagement_request_id != -1 {
    var response = scr_deltaDNA_processEngagementResponse(dd_engagement_request_id);
    if response >= 0 {
        var resultMap = ds_map_find_value(dd_engage_results_store, dd_engagement_request_id);
        var transactionID = ds_map_find_value(resultMap, "transactionID");
        var parameters = ds_map_find_value(resultMap, "parameters");
        var foo = ds_map_find_value(parameters, "foo");
        var baz = ds_map_find_value(parameters, "baz");
        dd_engagement_request_result = "engagement result: transactionID - " + string(transactionID) + ", foo - " + string(foo) + ", baz - " + string(baz);
        dd_engagement_request_id = -1;
        ds_map_delete(dd_engage_results_store, dd_engagement_request_id);
        ds_map_destroy(resultMap);
    } else {
        dd_engagement_request_result = "engagement failed";
    }
}
show_debug_message("Engagement info obj: finished http event code");

show_debug_message("Engagement info obj: executing http event code");

if dd_engagement_request_id != -1 {

var response = scr_deltaDNA_processEngagementResponse(dd_engagement_request_id);

if response >= 0 {

var resultMap = ds_map_find_value(dd_engage_results_store, dd_engagement_request_id);

var transactionID = ds_map_find_value(resultMap, "transactionID");

var parameters = ds_map_find_value(resultMap, "parameters");

var foo = ds_map_find_value(parameters, "foo");

var baz = ds_map_find_value(parameters, "baz");

dd_engagement_request_result = "engagement result: transactionID - " + string(transactionID) + ", foo - " + string(foo) + ", baz - " + string(baz);

dd_engagement_request_id = -1;

ds_map_delete(dd_engage_results_store, dd_engagement_request_id);

ds_map_destroy(resultMap);

} else {

dd_engagement_request_result = "engagement failed";

}

show_debug_message("Engagement info obj: finished http event code");

The code above is added to an HTTP Action on an object and added to the room in the example.

API Reference

Initialize

Script: scr_deltaDNA_initialize
Arguments:
- dd_environment_key: String, deltaDNA environment key for game
- dd_collect_url: String, collect url
- dd_engage_url: String, engage url
- dd_user_id: String, user id to use in submitted events
- dd_hash_secret: String, secret hash for md5, or “no_hashing” if hashing should not be used
- dd_file_store_size: integer, maximum size in bytes of file storage for events or 0 if no storage should be used.
- dd_file_store_path: String, path from working directory to a file where events should be stored if no net connection is available.
- dd_attempt_limit: integer, maximum number of attempts at event submission before event should be discarded.
Returns: 1 for success, any other value indicates failure

Trigger Event

Script: scr_deltaDNA_triggerEvent
Arguments:
- event_name: String, the event name value set up for the event in Portal
- event_param_ds: refs to ds_map, a GameMaker map set up with structure matching the event parameters structure within the event definition. Must be created with maps and lists flagged appropriately within their container structures.
Returns: 1 for success, any other value indicates failure

Upload Events

Script: scr_deltaDNA_uploadEvents
Arguments: None
Returns: 1 for success, any other value indicates failure
- If a net connection is present: submit any file stored events, events awaiting resubmission and queued events.
- If no net connection is present and file storage is turned on, dump queued events to file.
- If no net connection is present and file storage is turned off, get rid of stored events.

Generate UUID

Script: scr_deltaDNA_generateUUId
Arguments: None
Returns:
- a random formatted UUID

Generate Platform

Script: scr_deltaDNA_generatePlatform
Arguments: None
Returns:
- a platform value corresponding to one of the default enumeration values created for games. This is used in events if the game programmer does not supply their own value.

Process Collect Responses

Script: scr_deltaDNA_processCollectResponses
Arguments: None
Returns: 1 for success, any other value indicates failure

Processes waiting responses from Collect. If the response indicates a successful submission the response is discarded. Otherwise, if the response indicates an error for which a retry might be successful and the number of attempts does not exceed the limit, put the request back on the queue for submission.
This must be added to a HTTP Response event in order for submission queues to be correctly cleared.

Destroy

Script: scr_deltaDNA_destroy
Arguments: None
Returns: 1 for success, any other value indicates failure

Deletes global variables that contain the maps used for event queues.

Request Engagement

Script: scr_deltaDNA_requestEngagement
Arguments:
- decision_point: String, the decision point that the game is attempting to trigger
- engagement_parameters: ref to ds_map, a GameMaker map set up with structure matching the engagement parameters structure defined in portal. Must be created with maps and lists flagged appropriately within their container structures.
Returns:
- -1 if there is a problem, or a reference to the request that can be used to get the engagement response.

Request an engagement. Since this is asynchronous returns a reference to a response that can be checked for.

Process Engage Request

Script: scr_deltaDNA_processEngagementResponse
Arguments:
- engagement_response_ref: the value returned by the call to Request Engagement.
Returns:
- 1 if still waiting for a response, a negative number for an error, or 0 if complete. Once this method has returned 0, the dd_engage_results_store map will have a mapping between the engagement request reference and the key to a map corresponding to the JSON structure of the response.

Process an engagement response. Should be processed by a HTTP Response listener.

Known Issues

SSL does not work. You can only use plain http.
File storage for events won’t work for HTML5 compiled games.

Android

Android apps need to grant the “ACCESS_NETWORK_STATE” and “WRITE_EXTERNAL_STORAGE” permissions in the Android tab of global game settings.