Heyzap Android/iOS SDK

Heyzap Marmalade SDK

The Heyzap Marmalade SDK allows players to check-in to your game, driving viral growth and promoting your game on our social graph. For typical applications, the Heyzap SDK will only take a few minutes to integrate.

Find out more about the Heyzap Mobile SDK here.

Requirements

  • The Heyzap SDK supports Android 1.5+ when building for Android.
  • The Heyzap SDK supports iOS 3.0+ when building for iOS.
  • The Heyzap SDK requires internet access to pull information about your game.

SDK Location

The Marmalade SDK can be found in the Heyzap SDK zip file under the marmalade-sdk directory.

Step 1: Install the Heyzap SDK with Marmalade

  • Copy the marmalade-sdk directory into the same directory as your game’s mkb file. Then add the following line to your game’s mkb file:

    subproject marmalade-sdk/HeyzapMarmalade

Step 2: Open your Marmalade project

Using Visual Studio

  • Double click on your game’s mkb file to launch Visual Studio and begin the process of integrating with Heyzap.

Using Xcode

  • With a terminal, navigate to the directory where your game’s mkb is and execute the following command to launch Xcode:

    mkb YOUR_GAME_MKB.mkb

    Note: “YOUR_GAME_MKB.mkb” should be replaced with your game’s mkb filename.

Step 3: Load the Heyzap SDK in Marmalade

  • In the file where your game initialization code is run, add the HeyzapMarmalade header file by adding the following line at the top of the file:

    #include "HeyzapMarmalade.h"

  • In your game initialization code, add the following lines:

    if ( HeyzapMarmaladeAvailable() )
{
    loadHeyzap("YOUR_APP_ID_HERE","YOUR_APP_URL_HERE", true);
}

    Note: “YOUR_APP_ID_HERE” should be replaced with your Apple App ID if the game is going to be deployed onto an iPhone. “YOUR_APP_URL_HERE” should also similarly be replaced with your URL scheme for the iPhone (Please see App Store IDs & URL Schemes for more details.). If the game is not going to be deployed on an iPhone then these can safely be set to NULL.

  • You are now ready to add a checkin button to your game!

Step 4: Show a Checkin Button

To get the most checkins, and therefore drive increased growth, it is recommended you provide a ‘check-in’ button on your main screen or menu screen.

Note: Only display a checkin button in the released version if HeyzapMarmaladeAvailable() is true. This indicates that the HeyzapMarmalade extension is supported on the platform that the game is running on.

  • To bring up the check-in screen in your game, add a button somewhere in your game, and add the following code to the click action:

    if(HeyzapMarmaladeAvailable())
{
    checkinHeyzap();
}

    Note: If this is not in the same file as your game initialization code, then you will have to also add ‘#include “HeyzapMarmalade.h”’ to the top of the file, like you did when you originally loaded the Heyzap SDK.

You can find the source images for the checkin button in the sdk zip file.

Step 5: Prompt User To Check-in After Levels

You can additionally allow users to check-in with their score or level achievements. This normally goes at the end of a level and is a cool way to let them tell their scores/levels to their friends.

  • To bring up the post level check-in screen in your game, add a button somewhere suitable in a post level screen, and add the following code to the click action:

    if(HeyzapMarmaladeAvailable())
{
  checkinHeyzap("I just completed level 10!");
}

Step 6: SDK Icon Overlay

To highlight to players that your game has integrated with Heyzap, we recommend overlaying the Heyzap icon onto your game icon. This will increase the installs of your game, highlighting to potential players that they can check into Heyzap from within your game.

In order to generate the icons, claim your game through the Heyzap developer dashboard. Once you have claimed your game, view that games details and then click “SDK Icon Overlays”. From here you can download the icons.

Step 7: Testing & Releasing

Testing your game with Heyzap before release is essential. This will ensure the game fully leverages the Heyzap features from the instant it is live.

HeyzapMarmaladeAvailable() will always return false in the simulator. Checkin functionality will not be available in the Marmalade simulator, because it relies on system calls to the host devices. Be sure to test on the actual device to determine whether the Heyzap SDK is fully functional in your game.

Make sure to test your game with both the Heyzap application installed, and with Heyzap uninstalled, since the check-in process will be slightly different for each of those states.

If possible, send a copy of your game after integrating with the Heyzap SDK to integration@heyzap.com so we can help with the testing process and so we can better promote your game.

Please send a test build of the app to integration@heyzap.com. The UDID to build for is c313287485611e485cd25ae4f2326242401d3167. You can use http://www.testflightapp.com to help, or simply build directly.

Known Issues

Heyzap assets not being included in a deployment

If the Heyzap assets are not being deployed with the game then some images will not load. In order to fix this you can add the following line to your game’s mkf file.

    (PATH_TO_MARMALADE_SDK/source/iphone/heyzap-sdk/)
  	.

Replace PATH_TO_MARMALADE_SDK with the path to the Heyzap extension (marmalade-sdk). These assets are only required for an iPhone deployment, however including them in an Android build will not have any adverse effects, other than increasing the size of the game.

Advanced SDK Usage

Hide the Checkin Prompt Overlay

If you would prefer not to show the checkin prompt when loading the Heyzap sdk, you can adjust the third parameter to loadHeyzap:

    loadHeyzap("YOUR_APP_ID_HERE","YOUR_APP_URL_SCHEME_HERE", false).

This is not recommended as it will reduce the number of checkins your game will receive, limiting promotional and viral potential.

App Store IDs & URL Schemes

Obtaining an App Store ID

The App Store ID is a large number assigned to your app in iTunes Connect by Apple. You can get an App Store ID by completing all the steps necessary to submit an app short of uploading your application.

Setting Up A URL Scheme

The Heyzap SDK requires your game to configure a URL scheme so that we can relaunch your app after players check in. You can specify any URL scheme you want in your app.

  • To add a URL scheme in Xcode, go to the Info section of your build target settings and click Add in the bottom right of the screen. From there you will be presented with a menu, from which you select Add URL type.

    URL Scheme Settings

  • From there, you should specify the Identifier as yourappname and the URL scheme as yourappname. Make sure your chosen URL scheme contains no spaces or special characters.

    URL Scheme

Pausing the game when Heyzap is shown

If you would like to receive notifications when a Heyzap SDK screen is displayed and hidden, you can subscribe to notifications from the Heyzap extension using the following code.

    HeyzapMarmaladeRegister(HEYZAPMARMALADE_CALLBACK_HEYZAPWILLAPPEAR,&heyzapWillAppear,NULL);

This will then call the function “int32 heyzapWillAppear(void systemData, voiduserData)” when the Heyzap screen will appear. The following notifications are available,

    HEYZAPMARMALADE_CALLBACK_HEYZAPWILLAPPEAR
    HEYZAPMARMALADE_CALLBACK_HEYZAPDIDAPPEAR
    HEYZAPMARMALADE_CALLBACK_HEYZAPWILLDISAPPEAR
    HEYZAPMARMALADE_CALLBACK_HEYZAPDIDDISAPPEAR

When an appear notification is received by your game, you can set a flag that will stop the game rendering. When a disappear notification is received your game can reverse this flag and it will continue rendering the game.

Note: This functionality is currently only implemented on the iOS platform.

Additional Questions?

If you have any additional questions about integrating with our SDK, please email integration@heyzap.com and we’ll walk you through the process.