Introduction

HeyZap GameMaker Extension v2.0.6
Author: SilenGames
Download: YoYoGames Marketplace
Forum: GameMaker Community
Documentation for HeyZap GameMaker Extension v1.1

Migration from v1.1. If you are updating from previous version of extension please delete old extension from your project and carefully read documentation because many things have been changed. For example, Video functions have been removed. If you would like to display only video ads, please use the Interstitial functions, and set your game's "Blended Video" option to "Enabled: show ONLY video" under "Publisher Settings" for your game in HeyZap dashboard.

Initializing

1. Create an account. Firstly please register your account on HeyZap.com. You should add your Paments Details, at least PayPal account. It is very important.

2. Adding Apps and Networks. Then you can use HeyZap Integration Wizard to add your app and setup the 3rd-party networks you want to use with mediation. Please don't forget to Add your app to HeyZap dashboard with the same Android Package Name and iOS Bundle ID as you use in your GameMaker Global Game Settings (for example com.yourcompany.yourgame).

3. HeyZap and Fyber synchronisation. Fyber have bought HeyZap since summer 2016 and HeyZap is a part of Fyber networks for now. After first launch of the app you probably can not load and show any ads or you can see "Searching for third party network adapters" message in Test Mode for a long time. Just relaunch your app after several minutes and it should work fine. When you launch the app first time all your HeyZap data will transfer to Fyber servers. Sometimes it requires some time. If you can see your Ad Netwoks but they are showing as OFF, please try to get access to Fyber dashboard with login and password which you use to access HeyZap dashboard. If you can not access Fyber and see error message about "2-step authentication" please wait up to one day or send e-mail to developers@fyber.com for immediate authentication. Sorry for troubles but this process does not depend on me. You have to do it only once.

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.

Offer Wall is a new feature of HeyZap extension. To switch it on you should get access to Fyber dashboard with login and password which you use to access HeyZap dashboard. Then choose your app -> Ad Format -> Offer Wall Settings -> ON. To activate test offers for your app you should go to Settings and switch Test Mode on. Also you should send request to support@heyzap.com

Android Setup

OS Version: Recommended settings on the date of release: NDK-r12b, JDK 1.8.0_111, Target/Compile SDK 25, Min SDK 11, Build Tools 25.0.2, Support lib 25.2.0, Google Play Services rev.37. 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 and delete all strings from "Inject to Gradle" and "Inject to AndroidManifest" 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.


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


HyprMX mediation is not supported currently.

iOS Setup

OS Version: Heyzap works with iOS 7.0 and above. Use Xcode 7.3.1 or above for compile. You can compile test build only for a real device (simulator will not work).

Important! Unfortunately GameMaker is not able to work with Xcode Embedded Frameworks so you have to add all SDK by yourself.
0. Preparating. You should mark "Suppress build and run" option in GameMaker Preferences on iOS tab to prevent compilation fails in GameMaker.
1. Downloading. Firstly you should download all required SDK from HeyZap Docs section in "Step 2" block. You MUST do it on Mac, not on Windows (otherwise SDK will not work)! You have to download HeyZap SDK archive and all required Ad Networks SDK. You should mark those networks in "Step 1" block on HeyZap page and scroll down to "Step 4" block to find links. HeyZap Extension requre HeyZap SDK only so you can download only those Ad Networks which you are planning to use.
2. Extracting. HeyZap SDK archive contain "HeyzapAds.framework" and "FYBHZMediationTestSuite.framework" (find it in "ios-sdk" folder). You should create a folder on your Mac desktop (for example we will named it "SDK") and copy these files here. Each ad network's archive contain "*.embeddedframework" that you should copy to "SDK" folder too (if you see SDK8 folder inside the archive you should go to this folder to find framework).
3. Cleaning. After downloading and extracting was finished you can switch to GameMaker. You had to "Clean Project" in GameMaker (brush button) each time before compilation.
4. Compiling. You can compile your app in GameMaker now.
5. Adding. When your app appeared in Xcode you can add all those frameworks to Xcode. Open the "Project Navigator" tab in Xcode then select all of your framework from "SDK" folder and drag'n'drop them to "Framework" folder in Xcode (view small demonstration). Making sure that "Copy items" and "Create groups" options are checked in popup window before pressing Finish button. Wait about 5 seconds (10 for YYC) while your SDK appear in Frameworks folder.
6. Building. You can Build your app in Xcode now. Select your device and click "Play" button in Xcode.
Unfortunately you have to add frameworks each time after compilation in GameMaker (from step 3 to step 6). So, clean, compile, add, build, clean, compile, add, build... It is easy, is not it? ;) Also when your app will be ready do not forgot to archive your Xcode project before publishing on AppStore.

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.

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.

Warning! 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.

Warning! If you use GMS v1.4.1757 or below you should set Deployment Target to 7.0 in Xcode to prevent a lot of warnings during building process.

WARNING!!! If you want to Publish the app then you should make a new archive (which will include all frameworks) before using of Organizer. Click "Product" (on the top menu) and select "Archive".

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 before using any other functions.
If you use a 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. Rewarded ads require a manual fetching.
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 manually.

Show Ads:

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


Fetch Ads:

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


Check Ads Status (return TRUE or FALSE):

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


Offer Wall:

  • HeyZap_ShowOfferWall() - show Offer Wall.
  • HeyZap_OfferWallCheckReward() - you will need to call this function periodically to check for validated offers. Offers are validated server-side and can take any amount of time, depending on the offer. You can find example of usage in the Demo.
  • HeyZap_OfferWallAutoClose(true_false) - will make the Offer Wall close after the user interacts with one offer (TRUE or FALSE). Default: FALSE

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 it again.
  • HeyZap_RemoveBanner() - delete banner ad.
  • HeyZap_BannerGetWidth() - get banner width (works after banner was showed). Actually it return a screen width.
  • HeyZap_BannerGetHeight() - get banner height (works after banner was 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 (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

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

Interstial ad callbacks:
  • "heyzap_ad_loaded" - Interstial ad is loaded (or not). Script: HeyZap_Ad_Loaded
  • "heyzap_ad_shown" - Interstial ad is showed (or not). Script: HeyZap_Ad_Shown
  • "heyzap_ad_hidden" - Interstial ad is hidden. It is good place to fetch new ad if auto fetching is swithed off. Script: HeyZap_Ad_Hidden
  • "heyzap_ad_clicked" - Interstial ad is clicked. Script: HeyZap_Ad_Clicked
Reward ad callbacks:
  • "heyzap_reward_loaded" - Reward ad is loaded (or not). Script: HeyZap_Reward_Loaded
  • "heyzap_reward_shown" - Reward ad is showed (or not). Script: HeyZap_Reward_Shown
  • "heyzap_reward_hidden" - Reward ad is hidden. It is good place to fetch new reward ad. Script: HeyZap_Reward_Hidden
  • "heyzap_reward_clicked" - Reward ad is clicked. Script: HeyZap_Reward_Clicked
  • "heyzap_reward" - Reward ad is completed and user should be rewarded (or not). Script: HeyZap_Get_Reward
Offer wall callbacks:
  • "heyzap_offer_loaded" - Offer wall was loaded (or not). Script: HeyZap_Offer_Loaded
  • "heyzap_offer_closed" - Offer wall was closed. iOS event only. Script: HeyZap_Offer_Closed
  • "heyzap_offer_reward_error" - Error when trying to check reward. Script: HeyZap_Offer_Reward_Error
  • "heyzap_offer_reward" - User get reward from offer wall. "value" variable contain amount of reward. Script: HeyZap_Offer_Get_Reward
Banner ad callbacks:
  • "heyzap_banner_loaded" - Banner ad is loaded and showed (or not). Script: HeyZap_Banner_Loaded
  • "heyzap_banner_clicked" - Banner ad is 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.

Update SDK

You have opportunity to update SDK by yourself.

iOS: Just download new SDK from HeyZap Docs section and add it to Xcode as it has been already described above.

Android: Firstly you should download new SDK from HeyZap Docs section. Place new JAR files to "extensions/HeyZapExt/AndroidSource/libs. Old JAR files should be removed. Some SDK have "Libs" folder with additional JARs so you should place all of them to your extension's "libs" folder. Also you should check Android Manifest changes.
If SDK contain ARR files only (instead of JAR) you should to use ARR files in this case.

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.

Changelog

Extension v2.0.6 (12.04.2017):
- Android libs was updated.

Extension v2.0.4:
- iOS: Extension code was optimized for new SDK v10.3.0 and above.
- Android: Removes a time-out we had at SDK startup to wait for Fyber's SDK to initialize third party networks.
- Android: Removes some permissions for inMobi and Tapjoy. You should add them manually if you need those networks. Please check documentation for more info.

Extension v2.0.3:
- Banner size functions return correct width and height on iOS retina devices.

Extension v2.0.2:
- Facebook Ads works now on Android. Android "Min SDK" for Facebook Ads is 11.

Extension v2.0.1:
- Fixed an issue related to the uploading the app in the App Store through Xcode 8.

GameMaker 2 Support

You can use this extension with GameMaker Studio 2.

presskit() template by Rami Ismail (Vlambeer)

© 2016 Silen Games. All rights reserved.