Facebook Game Cards

Overview

This guide describes how to implement your own customized in-app Game Card redemption flow in just a few simple steps and outlines the user experience including recommended best practices.

User Experience

Below you can see the 3 stages of the standard in-app redemption flow.

First, the player clicks a "Redeem Game Card" button, provided by the developer, which is usually placed on the games' shop window. It's up to the developer to either use a basic link to invoke the Game Card Dialog or to design their own button:

Example: Marvel Avengers Alliance

Example: Dragon City

When the Game Card dialog is initiated, a Facebook Dialog is invoked, prompting the player to enter their Game Card PIN.

The Facebook Dialog that contains the text box for entering the Game Card PIN.

Then the player selects the in-app currency.

The dialog will display the different in-app currency options available in the game.

Implementation

This section will take you through the process of enabling players to redeem Game Cards directly in your game.

Define an in-app currency

Please follow the steps outlined in the payments tutorial to set up your in-game currency. The pricing of your og:product can be static or dynamic.

As we don't know the Game Card's value upfront, the Open Graph object instance created needs to represent a single unit of in-game currency. Based on the Game Card stored value we'll alter the quantity based on your in-game currency definition.

For example, with a US$10 Game Card redeemed in the below example, the player will be granted 50 units of the $0.20 currency.

Manage your in-game currency

Registering your currency

As a game can define multiple different in-app currencies, you need to specify which ones are meant to be enabled for in-app redemption of Game Cards explicitly. To register a product for in-app redemption, you'll need to issue a POST to the Graph API endpoint /APP_ID/payment_currencies with the currency_url and access_token (app access token).

POST https://graph.facebook.com/APP_ID/payment_currencies?currency_url=URL_TO_OG_OBJECT&access_token=APP_ACCESS_TOKEN

You can verify your App mapping by issuing a GET request to the same /APP_ID/payment_currencies with your app access_token (app access token).

GET https://graph.facebook.com/APP_ID/payment_currencies?access_token=APP_ACCESS_TOKEN

Note that you can add multiple currencies per app by issuing a POST request as described above for each currency product URL that you would like to support. If an app supports more than one currency the player will be able to select which one he would like to use in the currency selection dialog during the checkout flow.

Remove an in-app currency

If a currency is no longer needed you can remove it from the app by issuing a DELETE request to the same /APP_ID/payment_currencies endpoint with the currency_url and access_token (app access token).

DELETE https://graph.facebook.com/APP_ID/payment_currencies?currency_url=CURRENCY_URL&access_token=APP_ACCESS_TOKEN

Step 3: Invoke the Game Card Dialog

To enable players to redeem Game Cards directly from your game, you'll need to render the Game Card dialog using the JS SDK. The below sample can be used to render the Game Card redemption flow. The only major difference between this and the standard Pay Dialog is the additional parameter of action: redeem.

FB.ui({
      method: 'pay',
      action: 'redeem',
      request_id: 'sra93zd8em' //Optional, unique per transaction
    },
    callback
);  

Notice that you can also use the optional request_id parameter for extra security and payment tracking.

Step 4: Handling the callback

Upon completion, either in a succeeded or failed case, the dialog will call the provided callback function with data about the order. The return data is a JavaScript object, passed into the JavaScript callback function specified when you invoked FB.ui.

{
   "product":"URL_TO_THIS_WEBPAGE",
   "quantity":"",
   "user_currency":"USD",
   "method":"payments_get_item_price",
   "request_id":"sra93zd8em",
   "signed_request":"lFd_bGdvcml0aG0iOiJITUFDLVNIQTI1Ni..."
}

Decoding the signed_request reveals extra information about the initiated order including the product URL, the preferred currency of the player, the player's user_id and locale and so on.

Specifically to Game Card redemption, the parameter giftcard is added which contains the Game Card's amount and currency.

{
  "algorithm":"HMAC-SHA256",
  "expires":1370898000,
  "issued_at":1370893836,
  "oauth_token":"CAAGCibe0BykBAMD8dSKnzIQUNS1PTORgIuegrIC1EJu495cZASCfvlQlCZBeOyFnKyuAZDZD",
  "payment":
    {
      "product":"URL_TO_THIS_WEBPAGE",
      "quantity":"",
      "user_currency":"USD",
      "request_id":"sra93zd8em",
      "giftcard":
        {
          "amount":"10",
          "currency":"USD"
        }
     },
  "user":
    {
      "country":"us",
      "locale":"en_US",
      "age":
        {
          "min":21
        }
    },
  "user_id":"12355545545212"
}

If no in-app currency options are mapped to your game, the value of the Game Card is redeemed into the player's balance. In this case the JavaScript callback will return the following object:

{status="redeemed_to_balance"}

If the player cancels the redemption flow, your JavaScript callback will be passed the following error object:

{error_code=1383010, error_message="User canceled the order."}

Testing your implementation

You can generate test Pins using the "Retrieve Gift Card Test Pins" button on the payments tab of your app dashboard:

Note: At least one payment tester must be associated with the app in order to use test pins.

A collection of Pins will be generated supporting both USD and EUR. Each Pin can be used multiple times but it takes up to ten minutes until the same Pin can be used again.

{
 "payment_id":378600162255784,
 "quantity":100,
 "status":"completed",
 "test":true,
 "request_id":"sra93zd8em",
 "signed_request":"dA_3cu5yZsdfwJJuGIqmtMupE3zJR06UNw.eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsImlzc3VlZF9hdCI6MTM3MTA4MTM1NywicGF5bWVudF9pZCI6Mzc4NjAwMTYyMjU1Nzg0LCJxdWFudGl0eSI6Nywic3RhdHVzIjoiY29tcGxldGVkIn0"
}

Best Practices

Include Game Card redemption option on shop window

A prominent placement of the Game Card option is crucial to drive adoption of Game Card redemptions in your game. It is recommended to include the redemption option on the games' shop window to make potential payers aware that they can redeem Game Cards directly in your game.

The game Top Eleven Be A Football Manager is a great example for how Game Cards can be part of the shop window:

Example: Top Eleven Be A Football Manager

Announce launch of Game Card redemption flow in and outside of the game

When you're starting to offer Game Card redemption within your game it's a good idea to make players aware of this new option. This can be done, for example, by presenting players with a landing page or banner, which provides extra context on the new payment option.

It's also recommended to use your associated App Page to post about the launch of in-game Game Card redemption.

Offer small incentives upon Game Card redemption

Providing players with a small reward for using Game Cards to pay for in-game items have been very effective driver of payer conversions. This can range from giving away ex. free energy, lives or desirable in-game items to offering exclusive items to Game Card payers only.

Example: FarmVille