Introduction

HeyZap GameMaker Extension v3.0
Author: SilenGames
Download: YoYoGames Marketplace
Forum: GameMaker Community

Documentation for HeyZap GameMaker Extension v1.1
Documentation for HeyZap GameMaker Extension v2.0

Firstly please register your account on HeyZap.com.
Then you can use HeyZap Integration Wizard to setup the 3rd-party networks you want to use with mediation. Please don't forget to Add your app (with correct Android Package Name and iOS Bundle ID like com.yourcompany.yourgame) to HeyZap account.

Chartboost only! You need at least one Chartboost publishing campaign running to fetch and show Chartboost ads. You can create a publishing campaign on your Chartboost dashboard.

Migration from Extension v1: First extension uses SDK 9 too so all functions and callbacks is the same. Please read about HeyZap_GMBugFix() function for iOS.

Migration from Extension v2: Video Ads functions/callbacks was added and Offer Wall was removed. Please read documentation carefully.

Android Setup

OS versions: Recommended settings on the date of release: NDK-r12b (GMS2: NDK-r14b), JDK 1.8.0_111 (GMS2: JDK 1.8.0_131), Target/Compile SDK 25, Min SDK 14, Build Tools 25.0.3, Support lib 25.3.1 and lattest Google Repository. Please do not forget to update your Android SDK/NDK/JDK before compiling.

Google Play Services SDK is included in the extension. If you want to use "Google Play Services" extension from YoYoGames you should use at least v2.5.0. Please delete all strings from "Inject to Gradle" and "Inject to AndroidManifest (Application Level)" in "Google Play Services" extension properties on Android tab to avoid errors when compiling. You should do the same with "Google Analytics" extension if you want to use it.

AppLovin mediation requires you to manually enter the SDK Key to "HeyZapExt" extension properties -> Android tab -> Inject to AndroidManifest -> Application level.


inMobi mediation requires you to manually add permission to "HeyZapExt" extension properties -> Android tab -> Android Permissions.


HyprMX mediation isn't supported currently.

Note: If you get compile error "OutOfMemoryError: GC overhead limit exceeded" please go to Preferences -> Android -> Java Max Heap Size -> Set to 2 or 4

iOS Setup

Xcode version: Use Xcode 8.* for compile. You can compile test build only for a real device (simulator will not work).

Download Framework! Due 50mb limit of max size of extension I cut all third-party frameworks for iOS from extension.
Please download ZIP with iOS frameworks here - http://heyzap.silengames.com/get (194Mb)
Place "iOSSource" and "iOSSourceFromMac" to "YOUR_PROJECT_DIRECTORY.gmx\extensions\HeyZapExt" folder.

3-rd party extensions! If you use other extensions be careful with "Inject to Plist" settings. Sometimes they may overlap each other. For example, if you use Facebook SDK Extension you should overwrite "LSApplicationQueriesSchemes" key in "Inject to Plist" in HeyZap or Facebook extension properties to prevent duplicate keys and build errors.

Pausing! iOS advertisment widgets do not pause the game automatically. So you need to take care of this yourself. You can use *_shown and *_hidden callbacks to pause and unpause your app and sounds.

Google Play Service! If you use "Google Play Service" extensions for Android, please do this:
1. Delete "iOSSource" and "iOSSourceFromMac" folders from "extensions\GooglePlayServicesExtension" folder
2. Delete all strings in "System Frameworks" and " 3rd Party Frameworks" in GooglePlayServicesExtension -> Properties -> iOS
3. Uncheck "iOS" platform in GooglePlayServicesExtension -> Properties -> General
4. Uncheck "iOS" platform in GooglePlayServicesExtension -> GoogleMobileAds.ext -> Properties -> Copies to

Banner will be destroyed and created again if you hide it and then change it position. Also if you change orientation from portrait to landscape (or vice versa) you should destroy banner and create it again to prevent incorrect positioning.

MEGA WARNING!!! If you use GMS v1.4.1763 or above you MUST fix GameMaker bug using HeyZap_GMBugFix function. You can find example of usage in the Demo or in Functions docs below. It seems that this bug appeared after os_is_paused function support was added for ad containers in GMS v1.4.1763. If you show ad (or other content) and change device's orientation then your app will be frozen after closure of ad. You must change orientation again to unfreeze the app. It is not matter if you lock orientation or not because ad containers will rotate anyway. It affect all extensions and even Admob from YoYoGames. So you should use this fix until YoYoGames will fix this bug.

Functions

Initialization:
  • HeyZap_Init(HeyZap_Publisher_ID,HeyZap_Mode)

HeyZap_Publisher_ID (String):
Use your HeyZap Publisher ID here. You should initialize SDK with this function before using any other functions.
In Demo you should edit this function in Create event of "objControl" object.

HeyZap_Mode (Double):
0 - Normal mode with auto fetching. Interstitial ads will be cached automatically.
1 - Test mode. You can use a Mediation Test Suite to test each of the networks you've chosen.
2 - Normal mode with manual fetching. You should cache ads manyally.
3 - Amazon ads. Kindle Fire detection works automatically and covers most use cases. However, it is also possible for users with non-Kindle Android devices to manually install the Amazon Appstore and then install your Amazon app. To make sure that Heyzap will show Amazon ads in this case, you can use this mode.

Show Ads:

  • HeyZap_ShowInterstitial() - show interstial ads
  • HeyZap_ShowVideo() - show video ad
  • HeyZap_ShowReward() - show rewarded ad


Fetch Ads:

  • HeyZap_LoadInterstitial() - cache interstial ad if auto fetching disabled
  • HeyZap_LoadVideo() - cache video ad
  • HeyZap_LoadReward() - cache rewarded ad


Check Ads Status (return TRUE or FALSE):

  • HeyZap_InterstitialStatus() - interstial ad ready (or not)
  • HeyZap_VideoStatus() - video ad ready (or not)
  • HeyZap_RewardStatus() - rewarded ad ready (or not)
Warning! "Status" functions may not work properly. Using callbacks more reliable.


Banner Function:

  • HeyZap_AddBanner(POSITION) - show banner ad (need some time to load and display).

POSITION:
HeyZap_Banner_Top - show on top
HeyZap_Banner_Bottom - show on bottom

  • HeyZap_HideBanner() - hide banner ad. Use "HeyZap_AddBanner" function to show this banner again.
  • HeyZap_RemoveBanner() - delete banner ad
  • HeyZap_BannerGetWidth() - get banner width (works after banner loaded and showed)
  • HeyZap_BannerGetHeight() - get banner height (works after banner loaded and showed)

Warning! To show banner you must first set up Google Ads, Facebook Ads or InMobi in HeyZap dashboard.

Additional Functions:

  • HeyZap_GMBugFix() - you MUST use this function in GameMaker Studio v1.4.1763 or above for iOS platform (until the bug will be fixed by YoYoGames). You can find more info about the bug in iOS Setup docs above. Example of usage:

Callbacks

In Demo all callbacks placed in "Social" event of "objControl" object
Also you can use predefined scripts from Demo to set up callbacks.

Interstial ad callbacks:
  • "heyzap_ad_loaded" - Interstial ad loaded (or not). Script: HeyZap_Ad_Loaded
  • "heyzap_ad_shown" - Interstial ad showed (or not). Script: HeyZap_Ad_Shown
  • "heyzap_ad_hidden" - Interstial ad hided. Script: HeyZap_Ad_Hidden
  • "heyzap_ad_clicked" - Interstial ad clicked. Script: HeyZap_Ad_Clicked
Interstial ad callbacks:
  • "heyzap_video_loaded" - Video ad loaded (or not). Script: HeyZap_Video_Loaded
  • "heyzap_video_shown" - Video ad showed (or not). Script: HeyZap_Video_Shown
  • "heyzap_video_hidden" - Video ad hided. Script: HeyZap_Video_Hidden
  • "heyzap_video_clicked" - Video ad clicked. Script: HeyZap_Video_Clicked
Interstial ad callbacks:
  • "heyzap_reward_loaded" - Reward ad loaded (or not). Script: HeyZap_Reward_Loaded
  • "heyzap_reward_shown" - Reward ad showed (or not). Script: HeyZap_Reward_Shown
  • "heyzap_reward_hidden" - Reward ad hided. Script: HeyZap_Reward_Hidden
  • "heyzap_reward_clicked" - Reward ad clicked. Script: HeyZap_Reward_Clicked
  • "heyzap_reward" - Reward ad completed and user should be rewarded (or not). Script: HeyZap_Get_Reward
Banner ad callbacks:
  • "heyzap_banner_loaded" - Banner ad loaded and showed (or not). Script: HeyZap_Banner_Loaded
  • "heyzap_banner_clicked" - Banner ad clicked. Script: HeyZap_Banner_Clicked. Warning! Works for Android only.

Warning! Some ads don't return "*_clicked" callback. Do not use this callback for important events.

Warning! Some ads return "*_shown" callback after the closure of ads. Do not use this callback for important events.

SDK Versions

GameMaker Studio - v1.4.1747
GameMaker Studio 2 - IDE v2.0.5.77, Runtime v2.0.5.49

Android SDK:
HeyZap - v9.12.5
AdColony - v3.2.1
AdMob - v10.+
AppLovin - v7.2.0
Chartboost - v6.6.3
Facebook Audience Network - v4.25.0
InMobi - v.6.2.4
Leadbolt - v8.1
UnityAds - v2.1.0
Vungle - v4.1.0

iOS SDK:
HeyZap - v9.12.5 (v9.12.7 if you downloaded the archive after September 20, 2017)
AdColony - v3.1.1
AdMob - v7.21.0
AppLovin - v4.2.1
Chartboost - v6.6.3
Facebook Audience Network - v4.25.0
InMobi - v.6.2.1
Leadbolt - v8.2
UnityAds - v2.1.0
Vungle - v4.1.0

Update SDK

You have opportunity to update SDKs by yourself.

iOS: 1. Firstly you should download new SDK from HeyZap Docs section (you will find the link below after selecting the network).
2. Open the SDK archive and find ".framework" folder. Extract it. If you can't see "Versions" folder go to Step 5. But if you can see "Versions" folder you should delete two empty files: "Headers" and file with the framework name.
3. Then go to "Versions\A" and copy "Headers" folder and file with the framework name.
4. Go back to the root of ".framework" and paste those files here.
5. Now archive your framework folder and place it to "extensions\HeyZapExt\iOSSourceFromMac" folder. Old framework ZIP archive should be removed.

Android: Firstly you should download new SDK from HeyZap Docs section (you will find the link below after selecting the network). Place new JAR or AAR files to "extensions\HeyZapExt\AndroidSource\libs. Old JAR/AAR files should be removed. Some SDK have "Libs" folder with additional JARs or folders with SO files. In this case you should place all of them to your extension's "libs" folder. Also you should check Android Manifest changes. Note: If you use Game Maker Studio 2, you should use JAR files, instead AAR. You can extract JAR from AAR archive and rename it.

To update Google Play Service just go to HeyZapExt extension properties -> Android tab and change version number in "Inject to Grandle" string.

You can find latest version number on Google Play Services Guides. Do not forget to update Google Play Services in Android SDK Manager before changing the version number.

Removal of unused SDK

You have opportunity to remove unused SDKs to decrease compile time and project size.

iOS: You should delete unused Framework ZIP archive from "extensions\HeyZapExt\iOSSourceFromMac" folder and remove this Framework name from "Extension Properties -> iOS -> 3rd Party Frameworks" list.

Android: You should delete unused Libs from "HeyZapExt\AndroidSource\libs" and remove related Manifest injection from "Extension Properties -> Android -> Application Level" window.

Changelog

Extension v3.0.1 (02.05.2017):
- GameMaker Studio 2 package was added.

Extension v3.0.0 (01.05.2017):
- Switching back to HeyZap SDK 9 without Fyber. The reason: Fyber have some problems and HeyZap officially recommended to use SDK 9 instead SDK 10.

presskit() template by Rami Ismail (Vlambeer)

© 2017 Silen Games. All rights reserved.