Heyzap › Mobile Game Discovery

Heyzap 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.

Please see the separate Unity3D, Cocos2D or Marmalade SDK instructions if you are using these frameworks.

Requirements

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

SDK Contents

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

Heyzap.framework: Headers and code for the Heyzap SDK.
Heyzap.bundle: Graphical resources for the Heyzap SDK checkin buttons.

Step 1: Install & Load the Heyzap SDK

Drag Heyzap.framework and Heyzap.bundle from the Heyzap SDK zip into the Xcode project navigator.
Add the following line to your application delegate file:
```
#import <Heyzap/Heyzap.h>
```
Initialize the Heyzap SDK by adding the following line to your application delegate file inside application:didFinishLaunchingWithOptions:
```
[HeyzapSDK 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.

Add a check-in button to your screen, with a pre-filled checkin message:

// Set x and y to be the position on screen where you want to place the button
[self.view addSubview: [HeyzapSDK getCheckinButtonWithLocation: CGPointMake(x, y) 
                                  andMessage: @"I beat the monster on level 2!"]];

If you prefer to use your own button, you can prompt your player to check in with a message at any time by calling checkinWithMessage manually when you detect a touch event on your own buttons:
```
[[HeyzapSDK sharedSDK] checkinWithMessage: @"I beat the monster on level 2!"];
```

To get the most checkins, and therefore drive increased growth, it is recommended that you also show a checkin button on your main menu screen.

Inside the view controller that you want to display the checkin button, create an instance of the HZCheckinButton view and position it as required (make sure you do the import as above). For example:
```
// Set x and y to be the position on screen where you want to place the button
[self.view addSubview: [HeyzapSDK getCheckinButtonWithLocation: CGPointMake(x, y)]];
```
If you are using Interface Builder, add a UIView to your desired view and set the class to be HZCheckinButton.
If you prefer to use your own button, you can prompt your player to check in at any time by calling checkin manually when you detect a touch event on your own buttons:
```
[[HeyzapSDK sharedSDK] checkin];
```
After adding a checkin button, the basic installation process is complete! See Advanced SDK Usage for more customization options.

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

iOS 3.0 SDK Usage

If you want to release your game with compatibility for iOS SDK 3, you must ensure that some libraries are weakly linked. If this is not done, the game may crash on load when being run on an iOS 3 game.

In order to weak link these libraries, configure the build settings for your game by adding the following to the “Other Linker Flags” section of your build settings.

-weak-lSystem

Also change the linking options for UIKit.framework in the “Link Binary With Libraries” section from “Required” to “Optional”.

Image Resources

If you want to use the Heyzap check-in button image for your own buttons, you can access them through Heyzap.bundle:

[UIImage imageNamed:@"Heyzap.bundle/btn-sdk-checkin.png"]

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:

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

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:

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

Other Frameworks

If you don’t see your framework or view type listed here, it is easy to make your own plugin to support the Heyzap SDK.

See How to Make a Heyzap iOS SDK Plugin for more details, or email us at integration@heyzap.com to let us know what framework you are using.

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

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.

Heyzap Android/iOS SDK