Ad Provider Demos

Posted on 13 June 2014

We've released the new and expanded version 2 of all the ad provider demos. If you already have an earlier version, delete your downloaded copy from %localappdata%\GameMaker-Studio\demo and then download the demo again to get the new versions - GameMaker won't automatically update your existing copy.

 

 

Inside The Demo

You'll find extra functions for positioning/hiding/removing, plus better feedback as a social event is fired so you know if an ad loaded okay/failed/etc, and... the ability to load ads at x/y location.

 You can see the full list of new functionality for Google Mobile Ads in the next image:

We've also made the providers as functionally similar as possible. There are of course still differences (as some ad providers don't do interstitials, or Ad Colony only do interstitials and not banners, etc.) but where there is an overlap in what the provider allows we've kept the setup the same. This means you could change from one ad provider to another very easily in your game just by dropping in the new .gmez and then replacing the provider name before the _ in all function names and that would be the only change you'd likely need.

As you go through each demo, please see the readme action in objControl's Create event for more information, plus the various comments throughout the demo. Always start by reading the readme thoroughly, as it will explain if there are any build requirements or obvious pitfalls to be aware of - it also covers the results of our own testing.

Once you've had a read of the readme, run the app on your device and have a press of the buttons. You will find ads load and can be moved, removed, rewards are gained, etc., just fine. If you wish to test using your own ad provider settings the instructions for doing this will be covered in the readme, but for almost all of the providers you would be changing the keys written in that Initialise action in the above image.

As mentioned above and shown in that last image, you will now receive Social events when banners and interstitials change state. In this way you can reposition banners, track rewards, fire a push notification, promote an IAP, or whatever you want. However, be advised also that some providers do not have a system where the ad size is always supplied upfront and in these cases you must use the Social system in order to reposition your add before it becomes visible to your player, otherwise it will always appear at 0,0 - the providers which do this are explicitly covered in their demo.

 

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 GGS and the in-built functions offer on other platforms, 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 in the upper folder of your extension location inside the project folder. Inside the folder Explorer is showing you will be subfolders for iOS and/or Android (plus whichever platforms your extension covers, once we add more to the new system):

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 new-style "Studio v1.3" .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

Here is a really simple test project to try out yourself, which should give a solid idea of how to use the extensions. Create a new project, then create one object and add it into an empty room.

Add your extension via right-clicking the Extensions folder in the tree and choosing to Import - note that there is no need to use the old .gex library method to install these extensions.

Next, open your object and add in the events and actions shown in the following three images:

Make an executable of that project and it will toggle between showing two ads of different sizes and different screen locations quite nicely. You will also notice that loading one banner closes any existing banner and frees up the memory used.

 

In Summary

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 ad providers into your own game. Note that it's perfectly fine to include multiple ad providers as extensions in one project - iAds for your iOS release, Google for your Android version, for example - as they use unique function names.

 The next Early Access release will bring a slight change to the system for creating your own extensions (but that won't affect what we've been over here), plus the automatic generation of empty "stubbed" extension functions when you run on a platform your extension is not selected for in its properties window, so this guide will get another small update at that time.

 

FAQs

A few things to be aware of:

• On Android you must make an .apk via Create Executable - the runner won't do extensions (ADB will be telling you it can't find your extension class).
• On iOS you can use any of the three build methods, as your runner is generated custom to the project. You would want to have the iDevice plugged into the Mac when doing this to ensure that your runner updates correctly with each extension code change, rather than using the wifi web server.
• Making the app live on any given marketplace has nothing to do with if the ads work or not, apart from that Apple will only serve you test iAds if your project version is not live, then will only serve you real iAds if you're running the published version of your game.
• You should really be using at least v1.3.1344 now for any ad provider testing, as you'll probably have noticed the extensions system is a bit in flux at the moment - if you're using an older EA or 1.3 beta now the demo might not be "in-sync" with your version. These new demos were updated and exported from 1344 and so load perfectly fine in 1344.
• Although this guide is about just importing the .gmez, please be aware there is a bug in v1344/1347 with the "Add Android Source" right-click entry in that it doesn't put your source inside the correct folder. See the image at the end of this guide for more info if you are already in this situation, but this has already been fixed for v1354, so please update if you're about to start making an extension using pre-made source code. In the same way, if you're coming from an older EA version then your extension has likely stopped working - again, see the image.
• As mentioned above, you currently either need to leave your extension enabled on all platforms or you need to write stubbed extension functions in a new extension yourself. If you do not do this you'll get errors about missing functions when you try to run on Android your game which has iAds in and only enabled for iOS (for example).
• Also mentioned above, we've now matched what the old ad functions in GM:S 1.2 offered and we've added the Social events and other functionality to support future changes, so if you wish to have any further functionality in your project you will need to add this yourself - especially if the proposed change only works on one ad provider, etc.
• We won't always update the demos automatically/immediately as an ad provider releases an update (only when we become aware that their system change has broken the demo), so if you need a fix in the latest SDK and we haven't updated the demo already, you will likely have to implement the update yourself, but be aware this will require advanced knowledge and experience in Java/Objective-C to write your own custom code where required
• Similarly, Google Mobile Ads is the new name for AdMob (and that's why there is no "AdMob" demo) and unfortunately their roll-out of the new registration system is not available to all countries/territories at the moment, but obviously we had to use the current SDK and the one that most people would want us to use when making the demo. You could source the old SDK and integrate it yourself, but this will require advanced knowledge and experience in Java to write your own custom code where required. We cannot offer an older version of the SDK as it was under AdMob, so we are unable to offer assistance in this instance.

 

Fixing Projects Made In Older Releases

If you're stuck with your Android extensions never being found in an .apk, then you might have the EA97/v1344 bug detailed above. Your code will have been imported to the location shown here, when it should be inside the Java folder in order to work in v1344+. Depending on the GM version you started this project in, you may not even have a Java folder and would need to create it manually first - early EA builds wouldn't even have an AndroidSource folder.

You may want to just collect your source code files somewhere else for a moment and then make a new extension and re-import the code, rather than fixing manually.