Heyzap Developer Tools API

Attach a function to listen for an event from Heyzap. Events are triggered in response to messages you send Heyzap and after actions by the player. Be sure to listen for them to get information about the player and what she is doing.

Example

HeyzapTools.addEventListener("boughtItem", function (response:Object) {
  trace("User just bought the item: " + response.item_key);
});

Parameter: { game_key: String, clip: MovieClip (Optional) }

Events: userChanged

Loads the Heyzap tools. When the tools are finished loading, a userChanged event is fired, telling you which achievements and items are available and information about the user.

Example

import heyzap.as2.*;
HeyzapTools.load({game_key: "yourgamekeyhere"});

Remove an event listener function that was attached with addEventListener.

Example

HeyzapTools.removeEventListener("boughtItem", myBuyFunction);

Send a message to Heyzap to interact with the store, manage achievements, track analytics, or remember user data.

Check out the messages section of the api to see which messages you can send to Heyzap.

Example

HeyzapTools.send("achievementEarned", {achievement_key: "gold-shield"});

Parameter: { achievement_key: String }

Tell the user that they have earned an achievement. A small popup will be shown at the bottom of your game screen for a few seconds, and the achievement will be saved to the user's account.

Example

HeyzapTools.send("achievementEarned", {achievement_key: "black-belt"});

Tutorials

• How To Give Players Achievements Inside Your Game

Image

Parameter: { item_key: String }

Events: itemDetails

Fetch the details about a particular in-game item. If you want to fetch the information about more than one item, you should be checking userChanged events.

Example

HeyzapTools.send("checkItem", {item_key: "sword-of-power"});

Events: globalGameData

Fetch previously stored persistent information about your game.

Example

HeyzapTools.send("getGlobalGameData");

Events: userData

Fetch previously stored persistent information about the user currently playing your game. This data is also returned with every userChanged event.

Example

HeyzapTools.send("getUserData");

Tutorials

• How To Save And Load A Player's Game Progress

Parameter: { points: Number }

Events: userPointsGiven, userPointsChanged

Usually, you let a user earn points through achievements. To grant small, one-off amounts of points, eg. in-game experience, use giveUserPoints.

Example

HeyzapTools.send("giveUserPoints", {points: 3});

Tutorials

• How To Integrating Currency Into Your Game

Hide the panel that appears after you call showInvitePanel.

Example

HeyzapTools.send("hideInvitePanel");

Tutorials

• How To Show An Invite Friends Panel On Your Game

Hide the leaderboard that appears after you call showLeaderboard.

Example

HeyzapTools.send("hideLeaderboard");

Tutorials

• How To Show A Leaderboard In Your Game

Hide the panel that appears after you call showLeaderboardPanel.

Example

HeyzapTools.send("hideLeaderboardPanel");

Tutorials

• How To Show A Leaderboard In Your Game

Hide the panel that appears after you call showSharePanel.

Example

HeyzapTools.send("hideSharePanel");

Tutorials

• How To Show A Sharing Panel On Your Game

Events: popupShown, popupClosed

To send user to an invite screen where they can invite their Facebook and Twitter friends to your game. Attach this to an invite button in your game.

Example

HeyzapTools.send("inviteFriends");

Image

Parameter: { title: String, body: String }

The social stream is a stream of messages that periodically come up from the social bar. Call sendSocialStreamMessage to insert your own custom message into the social stream. For example, alert the player that his health is low.

Example

HeyzapTools.send("sendSocialStreamMessage", {title: "Warning!", body: "Your health is low!"});

Parameter: { global_game_data: Object }

Events: globalGameDataSaved

Save persistent information about your game, across all gameplays. For example, save high scores or how many times any user, across all of your gameplays, does an action.

This function will replace the previously stored global game data with any new data you set. That means you may want to call getGlobalGameData, modify the value you receive, and send the result back with setGlobalGameData.

You may store strings, arrays, numbers and inline objects.

Example

HeyzapTools.send("setGlobalGameData", {
  global_game_data: { high_scores: [["Rusty", 1500], ["Thomas", 1240]] }
});

Parameter: { user_data: Object }

Events: userDataSaved

Save persistent information about the user currently playing your game. For example, you can save scores, health, level progress information etc. and have them loaded in next time the user plays your game.

If you've ever used Flash's Shared Objects you'll be familiar with this concept. Using Heyzap's setUserData means persistent information can be saved to a user's account (or guest account) and game progress information reloaded next time. You can check userChanged events, or explicitly call getUserData to check what data you have previously saved.

This function will replace the previously stored user data with any new data you set. You may store strings, arrays, numbers and inline objects.

Example

HeyzapTools.send("setUserData", {
  user_data: { highest_level: 9, weapons: ["laser", "grenade"] }
});

Tutorials

• How To Save And Load A Player's Game Progress

Parameter: { user_id: String }

Tell Heyzap the internal user id you are using for the current user. We will then ping a URL on your server with this user id to let you know when users buy items or earn achievements. You'll need to set the "Secure Payments Callback Url" in the developer dashboard "edit game" screen.

Example

HeyzapTools.send("setUserId", {user_id: "custom-user-id"});

Parameter: { score: Number, share_message: String (Optional), show_share_popup: Boolean (Optional) }

Events: popupShown, popupClosed, userChanged

Store a user's score.

If show_share_popup is not set to false, then this also shows a popup that allows users to share their score to social networks such as Facebook and Twitter.

The share message defaults to "I just scored SCORE on GAMENAME. Try and beat me". A link to your game is always included with the update.

Example

HeyzapTools.send("shareScore", {score: 1000});

Tutorials

• How To Share Game Scores On Social Networks

Image

Parameter: { status: String, share_message: String (Optional) }

Events: popupShown, popupClosed

Show a popup which allows users to share their game status to social networks such as Facebook and Twitter.

The share message defaults to "I just STATUS on GAMENAME. Try and beat me". A link to your game is always included with the update.

Example

HeyzapTools.send("shareStatus", {status: "Completed Level 4"});

Tutorials

• How To Share Game Progress On Social Networks

Image

Events: popupShown, popupClosed, boughtItem, userChanged

Show the achievements popup where users will be able to browse which achievements are available to earn in your game.

Example

HeyzapTools.send("showAchievements");

Tutorials

• How To Show Your Player A List Of Possible Achievements

Image

Events: adStarted, adFinished

Start playing an ad in your game. Ads are a great way to earn money from every game play.

Make sure to listen for adStarted and adFinished events to know when to pause and play your game.

Example

HeyzapTools.send("showAd");

Image

Parameter: { x: Number (Optional), y: Number (Optional) }

Events: popupShown, popupClosed

Show a small panel that lets users invite friends to play your game from Facebook and Twitter. This panel stays visible until you call hideInvitePanel.

Leave out the x, y parameters to show the panel in the lower-right corner.

Example

HeyzapTools.send("showInvitePanel");

Tutorials

• How To Show An Invite Friends Panel On Your Game

Image

Parameter: { item_key: String }

Events: popupShown, popupClosed, boughtItem, userChanged

Show the purchase popup for a single item.

Example

HeyzapTools.send("showItem", {item_key: "example_item"});

Tutorials

• How To Display A Single Item To Sell

Image

Events: popupShown, popupClosed

Display a popup leaderboard panel. The leaderboard panel shows global high scores across your game as well as the current player's friends' high scores.

Players can also invite friends to play your game from this panel, which displays the "invite friends" panel.

Example

HeyzapTools.send("showLeaderboard");

Tutorials

• How To Show A Leaderboard In Your Game

Image

Events: popupShown, popupClosed

Display a small leaderboard panel at from the bottom of your game. The leaderboard panel shows global high scores across your game as well as the current player's friends' high scores.

Players can also invite friends to play your game from this panel, which displays the "invite friends" panel.

Example

HeyzapTools.send("showLeaderboardPanel");

Tutorials

• How To Show A Leaderboard In Your Game

Image

Parameter: { guest_mode: Boolean (Optional), title: String (Optional) }

Events: popupShown, popupClosed, userChanged

Show a login prompt where users are asked to login through Facebook, Twitter, or Heyzap. Pass guest_mode as true to let the user continue as a guest. The title parameter replaces the "Play now!" text.

Example

HeyzapTools.send("showLoginPrompt", {guest_mode: false});

Image

Events: popupShown, popupClosed, boughtItem, userChanged

Show the user profile popup where users can log in to save or load their game progress.

Example

HeyzapTools.send("showProfile");

Image

Parameter: { x: Number (Optional), y: Number (Optional) }

Events: popupShown, popupClosed

Show a small panel that lets users share on Facebook or Twitter that they're playing your game. This panel stays visible until you call hideSharePanel.

Leave out the x, y parameters to show the panel in the lower-right corner.

Example

HeyzapTools.send("showSharePanel");

Tutorials

• How To Show A Sharing Panel On Your Game

Image

Show the social bar. This takes up the bottom 25 pixels of the screen and remains there for the duration of gameplay.

To increase virality, you should show this on the bottom of your game throughout gameplay.

The social bar also includes the social stream. This engages your users by showing them relevant messages about what other players are doing in the game, as well as their own in-game actions.

Example

HeyzapTools.send("showSocialBar");

Tutorials

• How To Show The Social Bar On Your Game

Image

Parameter: { item_keys: Array (Optional) }

Events: popupShown, popupClosed, boughtItem, userChanged

Show the store popup where users will be able to browse and purchase items which you have for sale.

The list of store items will be restricted to the array of item keys if specified.

Example

HeyzapTools.send("showStore");

Tutorials

• How To Show An In Game Store To Sell Goods

Image

Parameter: { score: Number, leaderboard_key: String, name: String (Optional) }

Events: popupShown, popupClosed, userChanged

Store a user's score for a particular leaderboard. The popup also prompts the user to save there name and share there score on Facebook or Twitter

Example

HeyzapTools.send("submitScore", {score: 1000, leaderboard_key: 'normal'});

Tutorials

• How To Show A Leaderboard In Your Game

Image

Parameter: { points: Number }

Events: userPointsChanged

Usually, a user's points will debited when the user buys an item. To take away small amounts of points, eg. for in-game experience, call subtractUserPoints.

Example

HeyzapTools.send("subtractUserPoints", {points: 3});

Tutorials

• How To Integrating Currency Into Your Game

Parameter: { event: String }

Allows you to track when your users perform an in-game event. For example you may wish to count how many times players complete the game, reach a particular level, or even how many times users clicked on your homepage link from inside your game.

Example

HeyzapTools.send("trackEvent", {event: "finished-level-1"});

Tutorials

• How To Track Custom Game Events With Heyzap Analytics

Fired when an ad has finished playing after you call showAd. You should usually resume game play when this event is fired.

Example

HeyzapTools.addEventListener("adFinished", function (response:Object) {
  play();
});

Fired when an ad has started playing after you call showAd. You should usually pause game play when this event is fired.

Example

HeyzapTools.addEventListener("adStarted", function (response:Object) {
  stop();
});

Response: { item: Object }

Fired whenever a user buys an item in your game. You should unlock this item inside your game when you receive this event.

Example

HeyzapTools.addEventListener("boughtItem", function (response:Object) {
  trace("User bought item: " + response.item.name)
});

Tutorials

• How To Show An In Game Store To Sell Goods
• How To Display A Single Item To Sell

Response: { global_game_data: Object }

Fired in response to the getGlobalGameData message.

Example

HeyzapTools.addEventListener("globalGameData", function (response:Object) {
  trace("Highest score : " + response.global_game_data[0][1])
});

Fired after the setGlobalGameData message to confirm that the data has been saved successfully.

Example

HeyzapTools.addEventListener("globalGameDataSaved", function (response:Object) {
  trace("High score data saved")
});

Response: { item: Object }

Fired in response to the checkItem message.

Example

HeyzapTools.addEventListener("itemDetails", function (response:Object) {
  trace("User bought " + response.item.total_quantity_owned + " of " + response.item.name);
});

Fired whenever the store, achievements, profile or share popups are closed. You should unpause game play when this is fired.

Example

HeyzapTools.addEventListener("popupClosed", function (response:Object) {
  unpauseTheGame();
});

Tutorials

• How To Show An In Game Store To Sell Goods
• How To Display A Single Item To Sell
• How To Show Your Player A List Of Possible Achievements

Fired whenever the store, achievements, profile or share popups are shown. You should pause game play when this is fired.

Example

HeyzapTools.addEventListener("popupShown", function (response:Object) {
  pauseTheGame();
});

Tutorials

• How To Show An In Game Store To Sell Goods
• How To Display A Single Item To Sell
• How To Show Your Player A List Of Possible Achievements

Response: { user: Object, items: Object, achievements: Object }

Fired whenever new user information is received, ie. as soon as you call HeyzapTools.load(...) and whenever a user logs in or out. Use this information to find out which in-game items or achievements are available to the user. You can also use this information to display the user's username in your game if they are registered.

Example

HeyzapTools.addEventListener("userChanged", function (response:Object) {
  // Display the user's username if they are registered
  if(response.user.registered) {
    trace("User is logged in as " + response.user.username);
  }

  // Loop through all items and check how many the user owns
  for(var i:String in response.items) {
    trace("User bought " + response.items[i].total_quantity_owned + " of " + response.items[i].name);
  }

  // Loop through all the achievements and see if they have been earned
  for(var i:String in response.achievements) {
    trace("Has the user earned this achievement? ");
    trace(response.achievements[i].earned + ", achievement name " + response.achievement[i].name);
  }
});

Tutorials

• How To Prompt A Player To Login Through Facebook, Twitter, And Heyzap
• How To Get Information About The Player
• How To Save And Load A Player's Game Progress
• How To Integrating Currency Into Your Game

Response: { user_data: Object }

Fired whenever you send the getUserData message.

Example

HeyzapTools.addEventListener("userData", function (response:Object) {
  trace("User got to level : " + response.user_data.highest_level)
});

Tutorials

• How To Save And Load A Player's Game Progress

Fired whenever you save persistant user information.

Example

HeyzapTools.addEventListener("userDataSaved", function (response:Object) {
  trace("User data saved!");
});

Response: { points: Number }

Fired after the subtractUserPoints or the giveUserPoints message to show the user's new point value. The parameter "points" is for the total number of points the user now has.

Example

HeyzapTools.addEventListener("userPointsChanged", function (response:Object) {
  trace("The user now has " + response["points"] + " total points.")
});

Tutorials

• How To Integrating Currency Into Your Game

Response: { points: Number }

Fired after the giveUserPoints message to confirm that the points have been given to the user. The parameter "points" is for how many points the user was actually given. This is usually the number requested, although there is a daily cap on the number of points a user can get per day through the giveUserPoints messsage.

Example

HeyzapTools.addEventListener("userPointsGiven", function (response:Object) {
  trace("The user was given " + response["points"] + " points.")
});

Details about a single game achievement.

Example

{
  name: String,
  description: String,
  points: Number, // How many points is this achievement worth?
  earned: Boolean // Has the current user earned this achievement
}

Details about all achievements in your game.

Example

{
  <achievement_key> : <achievement>,
  <achievement_key> : <achievement>,
  <achievement_key> : <achievement>,
  ...
}

Some persistent information about your game. May contain strings, arrays, numbers and inline objects. The data you store for the game using setGlobalGameData will be the data that comes back here later.

Example

{
  number_of_players: 477805,
  highest_score: 10000,
  highest_score_username: "Bob"
}

Details about a single buyable/bought game item. This will always contain the latest information about an item.

Note: To save space, not all details about an item are returned with the userChanged event. To get all the information, use the checkItem message.

Example

{
  item_key: String,
  name: String,
  description: String,
  coinsPrice: Number, // Price of the item in Heyzap Coins
  pointsPrice: Number, // Price of the item in in-game points
  total_quantity_owned: Number, // Quantity the player now owns
  max_quantity_per_user: Number // Quantity the player can buy, null=unlimited
}

Details about all buyable items in your game.

Example

{
  <item_key> : <item>,
  <item_key> : <item>,
  <item_key> : <item>,
  ...
}

Contains information about the current user playing your game.

Example

{
  registered: Boolean, // Is the current user registered
  username: String, // Username of current user (null if unknown)
  user_data: Object, // Any user data saved for the current user
  coins_balance: Number, // The Heyzap Coins balance
  points_balance: Number, // The in-game points balance
  profile_picture_url: String // The profile picture url of the user, if any
}

The persistent information about the user currently playing your game. May contain strings, arrays, numbers and inline objects. The data you store for a user will be the data that comes back later.

Example

{
  highest_level: 6,
  enemies_killed: 45,
  last_boss_killed: "Steve",
  health: 89,
  items_collected: ["sword", "shield"]
}