Payer Promotion Dialog

Get new payers for your game

The Payer Promotion dialog helps bring more payers to your game, by encouraging players to make their first purchase. Facebook sponsors this feature, enabling you to offer certain people a discount on your game's virtual currency or items.

Overview

Some of the benefits of implementing the Payer Promotion feature are:

  • Get more paying customers — a user who pays once is more likely to pay again in the future. In one case, 20% of people who made a first-time purchase came back to spend more within a month. Similar results have been seen in other scenarios where the discount was offered to users who hadn't spent in the last 30 days.
  • Facebook sponsors this promotion - you receive your revenue share just as in a regular purchase.
  • Easy to implement — with just a few simple steps, you can start converting more players of your game into payers.
  • The promotion dialog will be displayed in the same window as your game.
  • Players can use their PayPal credentials as an option to obtain the discount.
  • No authorization cost on the player's account.
A sample Payer Promotion dialog

Implementation

Define a promotional item or bundle

First, you must implement either an item or virtual currency for sale within your game so that the promotion can be redeemed.

Make sure that you use discrete pricepoints ($1 or $0.99) for all the currencies supported on your game to increase conversion.

Example OG Object:

<html>
<head prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
  <meta property="og:type" content="og:product" />
  <meta property="og:locale" content="en_US" />
  <meta property="og:title" content=“30 Coins + 1 Bomb" />
  <meta property="og:plural_title" content=“30 Coins + 1 Bomb" />
  <meta property="og:image" content="http://friendsmash.com/images/coin64.png" />
  <meta property="og:url" content="http://friendsmash.com/opengraph/coin.html" />
  <meta property="og:description" content=“Free 30 Coins + 1 Bomb!” />
  <meta property="product:price:amount" content=“3.00"/>
  <meta property="product:price:currency" content="USD"/>
  <meta property="product:price:amount" content=“2.99"/>
  <meta property="product:price:currency" content="EUR"/>
</head>
</html>

Please note that the item or currency that is awarded in the promotion needs to have a maximum value of USD 3. If the value is greater than USD 3 or it's equivalent on other currencies, an error will be thrown.

Eligiblity

Before displaying the payer promotion, you should determine if the player is eligible to get the promotion. By issuing an HTTP GET request to player's ID Graph API endpoint, specifying the is_eligible_promo field (/USER_ID?fields=is_eligible_promo) with a user access token you can obtain the player's eligibility.

An example API request:

GET https://graph.facebook.com/USER_ID?fields=is_eligible_promo&amp;access_token=USER_ACCESS_TOKEN

This query returns the following data:

Parameter Type Value

is_eligible_promo

int

The value 1 indicating the player is eligible; 0 if the player isn't eligible

id

int

The user id

Invoking the Promotion dialog

Assuming the player is eligible for the promotion, you can invoke the custom Promotion dialog. When a player clicks on your custom promotion button, invoke the dialog using the Facebook's SDK for JavaScript FB.ui function:

var params = {
  action: 'payer_promotion'
  method: 'payer_promotion',
  quantity: 1,
  product: 'http://currency.object.url',
};

var callback = function(e){ console.log(e) };

FB.ui(params, callback);
Parameter Type Description

action

string

The constant payer_promotion

method

string

The constant payer_promotion

quantity

int

(optional) Defines the number of units you'd like to reward the user with. Defaults to 1.

product

string

The URL to your OG product or currency

request_id

string

(optional) Developer-generated unique identifier for the transaction. If not provided at the time of invocation, it'll default to the string discount: plus the Unix timestamp.

Promotion Fulfillment

Once the player has gone through the flow, the Javascript callback will be fired. The object passed as a parameter to the callback will have information that will help you fulfill the offer.

In addition, you'll also receive a webhooks update once the promotion has been fulfilled upon which you must award the player with the corresponding amount of your in-game currency or item.

Below is an example JavaScript object that would be returned in the case of a successful purchase completion.

{
  payment_id: 495869257196092,
  amount: "5.00",
  currency: "USD",
  quantity: "1", 
  status: "completed",
  request_id: "discount:1435780382",
  signed_request: "7QYHzKqKByA7fjiqJUh2bxFvEdqdvn0n_y1zYiyN6tg.eyJhbGCJxdWFudGl0eSI6IjEiLCJzdGF0dXMiOiJjb21wbGV0ZWQifQ"
}
Parameter Type Description

payment_id

int

The Facebook-generated unique identification number for this payment. Use this ID to query more details about the transaction through the Payment Graph API

amount

string

The total amount paid by the player.

currency

string

The currency in which the payment was made.

quantity

string

The quantity of the item the user purchase.

request_id

string

(Optional) The developer-generated unique identifier for the transaction. If not provided at the time of invocation, it'll default to the string discount: plus the Unix timestamp.

status

string

The status of the order. For the promotion dialog, this should always be set to completed on promotion redemption.

signed_request

string

Contains extra information about the purchase. For more information on handling the signed request, please refer to the How-to: Local Currency Payments - Order Fulfillment doc.

Best Practices

Below are a few recommended best practices that have shown to work best in games that are using payer promotions.

Check Eligibility Early

Make sure that you check the player's eligibility while loading the game. This way you can offer the promotion when the player lands in the game.

Caesar's Casino

Adding an incentive

We've seen that the promotion drives the best results once it's paired with a give away of extra in-game items. This pairing could range from a free set of lives or energy to rare items and resources.

Diamond Dash

Display offer on game load

A prominent display when the player loads the game or after their first round will ensure that the player knows that they're eligible for the promotion.

Heart of Vegas

Context and Timing

Showing the promotion at a point in the game where premium currency can best improve a player's play experience could maximize the impact of your promotion. For example, showing the promotion alongside with a free extra life just after the player has run out of lives would maximize the impact of your offer.

Criminal Case

Add the offer to your current store

Adding the offer to your game's store will remind your players that they're eligible for the promotion when they open the store.

Top Eleven

Make a Personalized Offer

Personalized offers can yield more interest from your players. Giving a player different options to choose from will represent better conversion rates for the promotion.

Bingo Blitz