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 ad provider demos. 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.
What's Changed
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
- Amazon
- Moga
- Ads
- Analytics
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 Advertising Tab. There you can select the target platform from the left and then select the ad provider required. For Android and iOS you have a series of tick boxes which you can choose to support the given advertiser, and checking any one of them will show the following prompt:
As you can see, selecting any ad 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 advertiser - 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 Ads 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 Advertisers tab for the platform).
If you wish to see all the functions available to you from the ad provider, simply open the extension resource, as shown for Google Mobile Ads in the next image:
Note that functionally between ads providers is as similar as possible so as to make setting up and using them as easy as possible, so while this tutorial covers Google, the other ads providers should be more or less exactly the same to set up and use. 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 extension 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. For more detailed information you can also open the included Help file, as explained above.
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 Asynchronous 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 can export the extension out for use in your own project, mainly as backup but also incase you need to add them but can't access the marketplace for whatever reason. 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 as explained above from the Marketplace (Global Game Settings > Advertisers > Check Provider > Download > Add to project).
Next, open your ads controller 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.
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.4.1568 now for any ad provider testing, and will require the next EA release to use the above new features for downloading.
- We won't always update the demos and extensions 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. Be aware this will require advanced knowledge and experience in Java/Objective-C to write your own custom code where required
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.