In-Game Gifting

Let your players send paid gifts to their friends

With in-game gifting, you can enable players to purchase in-game items as gifts for their friends or group members who also play the game. Players that receive a gift will get a notification, so enabling gifting can drive both re-engagement and revenue.

Overview

This feature is in BETA stage.

Some benefits of this feature are:

  • Re-engagement - Players who received a gift are likely to login to your game. This feature is effective when re-engaging lapsed players.
  • Revenue Increase - Players buy gifts to help their friends in the game.

Implementation

First, define the gift items you want people to be able to purchase as products. As with regular payments, you'll need to build the user experience where a player can select the different items that can be gifted.

User Experience

Once a player has selected a gift to send on your UI, they must click a gift button to send. This button launches the in-game gifting dialog where the player can first choose a friend to send this gift to.

Recipient dialog

To open the in-game gifting dialog, you should use the FB.ui method of the Facebook's SDK for JavaScript, specifying the product parameter for the gift the player wants to send. You can create your own gift recipient selector dialog by using the recipient ID in the to field. If the to field is provided when the gift dialog is invoked, the friend selector step of the dialog will be skipped and the player is taken to the payment dialog. You can use any user ID in the to field, including people that aren't friends of the sender.

FB.ui({
    method: 'gift',
    product: 'URL_TO_YOUR_PRODUCT',
  },
  function(response){console.log(response);}
);

Send gift to specific recipient, where the to parameter is the recipient ID:

FB.ui({
    method: 'gift',
    product: 'URL_TO_YOUR_PRODUCT',
    to: 'USER_ID'
  },
  function(response){console.log(response);}
);
Parameter Description Required

product

This is the ID or url of a payment product.

Required

to

A user ID. This may or may not be a friend of the sender. If this is specified by the app, the sender won't have a choice of recipients. If not, the sender will see a multi-friend selector.

Optional

Once the dialog is shown, the player can choose a friend to send this gift to. Selecting a friend will launch the payment dialog.

Payment Dialog

If the payment was successful, your game must fulfill the purchase by awarding the gift at one of two possible times:

  • Once the payment has been confirmed
  • When the recipient logs into your game from the gift notification

Facebook sends a notification to the recipient with the name of the gift included.

Notification
Notification

Additional to the regular payment information, the callback data will also contain a receiver parameter and a gift_requests parameter. The response contains data in the same format you receive when you send an app_request:

{
   "amount":"0.01",
   "currency":"USD",
   "gift_request":
       {
          "request":"1483068188614502",
          "to": [1477568509157318]
       }
   "payment_id":"624623807654732",
   "quantity":"1",
   "receiver":"1477568509157318",
   "signed_request":"lFd_bGdvcml0aG0iOiJITUFDLVNIQTI1Ni...",
   "status":"completed"
}

If the transaction fails, you will receive an error code and message with more information about the cause.

Gift Requests

All payment objects created via the in-game gifts flow will include a gift_requests field. This is an apprequest object associated with the payment object, and it includes the object id for gift_requests as well as info about the sender, receiver and game app. You have to explicitly query this gift_requests object via graph API:

GET graph.facebook.com/{payment-id}?fields=items,actions,gift_requests

Here's a sample response for a payment object with gift_requests:

{
  "actions": [
    {
      "type": "charge", 
      "status": "completed", 
      "currency": "USD", 
      "amount": "0.01", 
      "time_created": "2014-11-10T14:42:40+0000", 
      "time_updated": "2014-11-10T14:42:42+0000"
    }
  ], 
  "id": "555885171208546", 
  "created_time": "2014-11-10T14:42:40+0000", 
  "gift_requests": {
    "data": [
      {
        "application": {
          "name": "Friend Smash! - Dev", 
          "namespace": "friendsmashsampledev", 
          "id": "844042765624257"
        }, 
        "created_time": "2014-11-10T14:42:42+0000", 
        "from": {
          "id": "382172578615968", 
          "name": "Guannan Pu"
        }, 
        "message": "I hope you like my gift!", 
        "to": {
          "id": "1509388185975350", 
          "name": "Connor Treacy"
        }, 
        "id": "902190936459036_1509388185975350"
      }
    ], 
    "paging": {
      "cursors": {
        "before": "OTAyMTkwOTM2NDU5MDM2XzEwMDAwNzEyNTQ4MDk5MQ==", 
        "after": "OTAyMTkwOTM2NDU5MDM2XzEwMDAwNzEyNTQ4MDk5MQ=="
      }
    }
  }
}