Heyzap Android/iOS SDK

Heyzap Cocos2D (iOS) SDK

The Heyzap 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 SDKs here.

Requirements

  • The Heyzap SDK supports iOS 3.0+
  • The Heyzap SDK requires internet access to pull information about your game.

SDK Contents

The Cocos2D SDK can be found in the Heyzap SDK zip file under the cocos2d-sdk directory. The cocos2d-sdk directory contains:

  • Heyzap.framework: Headers and code for the Heyzap SDK.
  • Heyzap.bundle: Graphical resources for the Heyzap SDK checkin buttons.
  • HeyzapCocos2D: The Heyzap Cocos2D helper library

Step 1: Install & Load the Heyzap SDK

  • Drag Heyzap.framework, Heyzap.bundle and HeyzapCocos2D from the cocos2d-sdk folder in the Heyzap SDK zip into the Xcode project navigator.

    Drag Files to XCode

  • Import the Heyzap SDK in your application delegate file:

    #import "HeyzapCocos2DSDK.h"

  • Initialize the Heyzap SDK by adding the following line to your application delegate file inside application:didFinishLaunchingWithOptions:

    [HeyzapCocos2DSDK startHeyzapWithAppId: @"YOUR-APP-STORE-ID-HERE"];

    It is important that you to replace YOUR-APP-STORE-ID-HERE with your game’s App Store ID. See Obtaining an App Store ID for details. The call to startHeyzapWithAppId should be done as soon as possible after your game is initialized to ensure that check-ins run smoothly.

  • Ensure your app can be opened by a custom URL scheme. Heyzap needs the URL scheme so that we can switch back to your game after players check in. See Setting Up A URL Scheme for details.

  • You are now ready to add checkin buttons to your game!

Step 2: Prompt User To Check-in After Levels, High Scores etc.

Allow users to check-in with their score or level achievements. This normally goes at the end of a level and is an effective way to let them share their scores/levels with their friends.

  • Import the Heyzap SDK:

    #import "HeyzapCocos2DSDK.h"

  • Add a check-in button to your screen:

    // Create a menu item image button
CCMenuItem *heyzap = [CCMenuItemImage itemFromNormalImage:@"Heyzap.bundle/btn-sdk-checkin.png" 
                                            selectedImage:@"Heyzap.bundle/btn-sdk-checkin-down.png"
                                                   target:self
                                                 selector:@selector(heyzapCheckinTapped:)];

// Set x and y to be the position on screen where you want to place the button
heyzap.position = ccp(x,y);

// Add it to the menu (or use your existing menu instead)
CCMenu *Menu = [CCMenu menuWithItems:button, nil];
[self addChild:heyzapMenu];

  • Create the selector function to handle the tap event on the checkin button:

    - (void)heyzapCheckinTapped: (id)sender {
    [[HeyzapCocos2DSDK sharedSDK] checkinWithMessage: @"I just completed level 5!"];
}

  • If you prefer not to use the CCMenuItemImage class, make sure you call checkinWithMessage as above when the user taps the checkin image.

Step 3: Show a Checkin Button on Your Game’s Menu Screen

  • Import the Heyzap SDK:

    #import "HeyzapCocos2DSDK.h"

  • Add a check-in button to your screen:

    // Create a menu item image button
CCMenuItem *heyzap = [CCMenuItemImage itemFromNormalImage:@"Heyzap.bundle/btn-sdk-checkin.png" 
                                            selectedImage:@"Heyzap.bundle/btn-sdk-checkin-down.png"
                                                   target:self
                                                 selector:@selector(heyzapCheckinTapped:)];

// Set x and y to be the position on screen where you want to place the button
heyzap.position = ccp(x,y);

// Add it to the menu (or use your existing menu instead)
CCMenu *Menu = [CCMenu menuWithItems:button, nil];
[self addChild:heyzapMenu];

  • Create the selector function to handle the tap event on the checkin button:

    - (void)heyzapCheckinTapped: (id)sender {
    [[HeyzapCocos2DSDK sharedSDK] checkin];
}

  • If you prefer not to use the CCMenuItemImage class, make sure you call checkinWithMessage as above when the user taps the checkin image.

Step 4: 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 5: 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.

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.

Please also 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.

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

Advanced SDK Usage

Choosing Which URL Scheme is Used By Heyzap

If your game defines multiple URL schemes and you wish to choose a specific one to use when Heyzap switches back to your game, you can set this at any point prior to the checkin button being pressed:

[[HeyzapCocos2DSDK sharedSDK] setAppURL: [NSURL URLWithString: @"coolapp://"]];

Displaying a custom application name

To change the name of the application used inside of the SDK, set the application name at any point prior to the checkin button being pressed:

[[HeyzapCocos2DSDK sharedSDK] setAppName: @"<YOUR APP NAME>"];

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

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.