NOTE: This will be available Early Access 1.99.421+ and Beta version 1.4.1630+.
We've released the new and expanded version 3 of all the analytics provider extensions. If you already have an earlier version, delete your downloaded copy from %localappdata%\GameMaker-Studio\demo and follow these steps to get the new versions.
NOTE: If you are still on the Standard version of GameMaker: Studio, you can still download the extensions as before from the Demos Tab when you start up GameMaker. The testing and use procedures are the same as those mentioned below from "Inside The Demo" onwards.
In the coming Early Access update (and the following 1.4 update) support for the following 3rd party API's will be getting removed from the GameMaker: Studio runner and added to the Marketplace as extensions, across all platforms that support them:
- Google Play
- Google APK Expansions
- Google Licensing
These changes were made to enable faster updating of the core APIs and SDKs as the companies that produce them add new features and change how they work. The previous method of having them integrated within the GameMaker: Studio IDE meant that when one has been changed, you would have to wait for a full update to GameMaker to get the fix, which can sometimes be several weeks. Now, however, with this change to an extension based system, these updates can be pushed out far quicker for you to download and integrate into your game, and you can get examples of use direct from the Marketplace.
Getting The Extensions
To get the extensions you now no longer need to use the Demos tab. Instead you simply open up the Global Game Settings and browse to the Analytics Tab. There you can select the target platform from the left and then select the analytics provider required. For Android and iOS you have a series of tick boxes which you can choose to support the given analytics, and checking any one of them will show the following prompt:
As you can see, selecting any analytics provider will prompt you to install it, and if you select "Yes" you will be directed to the Marketplace to download it ready for installing in your project.
IMPORTANT! It is only the extension itself which is downloaded, with no extra files or demo of how to use. To get the demo - which contains example code as well as setup instructions - you can click the link next to the analytics provider - in the Global Game Settings - and it will take you to the specific Marketplace listing where you can download them. It is recommended that you do this first if you have never used ads to get an idea of how they work, and the rest of this article will explain a bit more about these demos.
NOTE: If you have not already created a YoYo Account, then one will be required to get access to the Marketplace, and even if you have one, you may be requested to log in before the download will proceed.
Once you have chosen to download the extension it will be added to your Marketplace library, and you can then add it to your project from there.
Inside The Demo
If you've never used the Analytics extensions before, then you'll have downloaded the demo from the Marketplace. The demo file contains all the functions for the extension as well as example code and comments explaining how to use them, and there is also an included Help file - this can be opened by going to the Included Files section and double clicking on the file (as mentioned above, you can get the demos by clicking the link beside the provider in the Global Game Settings Analytics tab for the platform).
Functionally the two analytics providers are similar but of course there are still differences (Google Analytics has an extra function). Where there is an overlap in what the provider allows we've kept the setup as much the same as possible. This means you could change from one analytics provider to another very easily in your game just by dropping in the new .gmez and then replacing the provider name in all function names and that would be the only change you'd likely need.
As you go through each demo, please check the Helpfile that is bundled with the demo for more information, as it will explain if there are any build requirements or obvious pitfalls to be aware of. You can find the helpfile from the Included Files in the resource tree, as shown in the image below:
You can open the helpfile by right clicking on the resource and selecting "Open in Explorer". Once you've had a read of the Helpfile, you should retrieve your tracking ID values from the respective analytics provider. Note that you will need to provide different keys for Android and for iOS, so make sure you have set up two different projects to track in the analytics provider dashboard for your game.
- You can find out more about setting up Google Analytics here: Analytics - Google Analytics
- You can find out more about setting up Flurry Analytics here: Analytics - Flurry
Once you have your tracking Ids you can add them into the Create Event code of the "obj_Control" object and test the demo on your chosen device. Note that for Android, you need to do a full APK build for them to work. Since there is no direct feedback with analytics, the demo itself will only display console messages to show the status of the analytics events called, however if you are testing with Google analytics, the real-time reporting on the website has improved, and you can now see events as they are triggered which is very handy for testing. It shows results almost straight away for iOS, but for Android it can take a while for something to show up because the android SDK only dispatches results intermittently.
Exploring The Extension Code
If you want to see exactly how the extension is made up, or you wish to customise any of the functionality (or add new stuff - the demo is done now and we've matched and even exceeded what the in-built functions offered previously, so if you want something extra you'll likely have to write it yourself using the provider's own SDK documentation), you will need to explore the source code.
To do this, right-click the extension in the tree and choose Open Extension Directory:
This will open a new Explorer window on the Extension files, and inside this folder you will find the two subfolders for iOS and/or Android (plus whichever platforms your extension may cover):
Inside those folder you will see the structure for the extension, plus the source code itself. Understanding the new languages is far too large a topic to go into here, but you will see Android extensions use Java .java files and iOS uses Objective-C .h header files and .mm implementation files. Feel free to have a read through the code and make changes if you wish.
Exporting A .gmez Extension
Once you're happy with testing the demo and you've understood what's going on with the code, you should export the extension out for use in your own project. To do this, you must use the .gmez format, not the legacy GameMaker .gex extension type. Simply right-click the extension entry in the tree and choose Export extension from the context menu, as shown below:
This will give you a save dialogue, so pick a location and your new file will be written out. Locate the file and you'll be ready for the next stage.
Using The .gmez In Your Own Project
To use the extension in your own games, simply add the extension required as explained above from the Marketplace (Global Game Settings > Analytics > Check Provider > Download > Add to project). Once the extension is added, you will need to initialise the extension functions in your game - this only needs done once, so you would do this in the first instance of the first room, and can use the Game Start event, for example - with the following code:
As you can see, this will select the correct tracking ID to initialise based on the OS that is running the game. If you are only making an iOS or only making an Android game then you can omit the OS check and simply use the init function your tracking ID.
You can then add the following code at the points in your game where you require an event to be sent to the analytics provider (for example at the start of a new level, or when the player dies, etc...):
You can use the other analytics functions in exactly the same way (see the helpfile for the correct arguments), with the _ext functions permitting additional data to be sent along with the event. Don't forget that if you are updating an existing game, you will need to swap out the legacy functions for the extension functions, as they cannot be used together without getting errors.
So now you've had a look at the demo, figured out how it works, and seen a quick example of how to integrate an extension into a new project. You should hopefully be able to quite quickly drop any of the analytics providers into your own game. Note that it's perfectly fine to include multiple analytics providers as extensions in one project - Flurry for your iOS release, Google for your Android version, for example - as they use unique function names. Just make sure that your code checks the OS and uses the appropriate function call.