Game Gifts

To make the gameplay more collaborative and improve the social engagement, your game can allow players to send and request gifts of in-game resources or items by using the game gifts API. Your game can display a built-in user interface (UI) provided by Play Games services that make it easy for players to send and request gifts for in-game items and resources to friends in their Google+ circles. Request recipients receive notifications on all devices on which the recipients are logged in (unless notifications is disabled).

Warning: Your game must not send, request or accept an in-game gift without an explicit approval from a user. Doing so violates the terms of service.

Game gifts basics

There are two types of requests that players can send using the game gifts feature in Play Games services:

  • wish requests to ask for in-game items or some other tangible form of assistance from their friends.
  • gift request to send in-game items or some other tangible form of assistance to their friends; for example, players can gift " lives" to each other to extend gameplay.

A player can specify one or more target request recipients from the default request sending UI. A gift or wish can be consumed (that is, accepted by a recipient) or dismissed by a recipient. Each request can be consumed only once. Requests expire after a period of time if they are not consumed.

A request has the following key properties:

Name Description Notes
Type Indicates whether the request is a gift or a wish.
  • Gift. Use this request type if sending an in-game item or other tangible form of assistance to another player.
  • Wish. Use this request type if requesting an in-game item or other tangible form of assistance from another player.
Developer-defined.
Payload A byte array that contains data to send with the request.  Developer-defined.
Request lifetime Indicates how long (in days) the request should persist if the recipient takes no action. This value must be in the range of 1 to 14 days (inclusive). After this time elapses, the request may be deleted by Play Games services at any time. Developer-defined.
Icon A bitmap that is displayed as the request icon. Developer-defined.
Description A string that is displayed in the request sending UI to provide additional context for the request. Developer-defined.
ID A unique ID for the request. Set by Play Games services.
Sender Information about the player that sent the request. Set by Play Games services.
Creation timestamp The server timestamp when the request was created. Set by Play Games services.
Expiration timestamp The server timestamp after which the request is eligible for deletion by Play Games services. Set by Play Games services.
Recipient status Indicates whether the request has been accepted or is pending. Note that if a request is dismissed by a recipient, the sender will only see the recipient status as RECIPIENT_STATUS_PENDING.

 

Sending a request

To send a gift or wish request, follow these steps:

Call SendGiftRequest in GooglePlayManager to bring up the default request sending UI so that the player can select a recipient for the request. In the call you must specify the request type (TYPE_GIFT or TYPE_WISH). You can use the payload input parameter to provide additional data in byte array format to indicate what game-specific items are being requested or sent. 

int requestLifetimeDays = 1;
string description = "Here is some pie";
string pieGiftPayload = "PIE_GIFT_PAYLOAD";
GooglePlayManager.Instance.SendGiftRequest(GPGameRequestType.TYPE_GIFT, requestLifetimeDays, pieIcon, description, pieGiftPayload);

 

You can also find out Send Gifts action result(represented by GooglePlayGiftRequestResult object) with the ActionSendGiftResultReceived action:

GooglePlayManager.ActionSendGiftResultReceived +=  OnGiftResult;
int requestLifetimeDays = 1;
string description = "Here is some pie";
string pieGiftPayload = "PIE_GIFT_PAYLOAD";
GooglePlayManager.Instance.SendGiftRequest(GPGameRequestType.TYPE_GIFT, requestLifetimeDays, pieIcon, description, pieGiftPayload);


private void OnGiftResult(GooglePlayGiftRequestResult result) {
	Debug.Log("Gift Send Result:  " + result.code.ToString());
	SA_StatusBar.text = "Gift Send Result:  " + result.code.ToString();
}

After the user selects one or more request recipients from the UI, the request is sent by the game gifts API to the Play Games services. Play Games services then create a GameRequest object to represent the request and routes this request object to the target recipient. To learn how your game can accept an incoming request, see the Handling requests section.

Launching your game from a request notification

By default, request recipients will see a notification appeares on their devices when they receive a request from friends in their Google+ circles. If the recipient has already installed your game on the device, the recipient can simply expand and click on the notification to launch a UI to select whether to accept the request. After the recipient makes this selection, the system automatically launches your game.

Note: If the recipient does not have your game installed on the device, the recipient is directed to the Google Play store to download the game.

Next, your game should retrieve the list of requests that the recipient selected. The list of requests is represented as GPGameRequest object.

The following snippet shows how to get pending requests list:

GooglePlayManager.ActionPendingGameRequestsDetected += OnPendingGiftsDetected;

private void OnPendingGiftsDetected(List<GPGameRequest> requests) {
	foreach(GPGameRequest request in requests)	 {
		Debug.Log(request.id);
	}
}

If there are some pending requests detected, we should give a user opportunity to accept or decline the requests. We can do this by showing default Play Service UI dialog box. To learn how to accept requests, see the Handling requests section.

Handling requests

When the pending requests are detected, let's bring up the dialog box:

GooglePlayManager.ActionPendingGameRequestsDetected += OnPendingGiftsDetected;

private void OnPendingGiftsDetected(List<GPGameRequest> requests) {
	foreach(GPGameRequest request in requests)	 {
		Debug.Log(request.id);
	}
}

AndroidDialog dialog = AndroidDialog.Create("Pending Gifts Detected", "You got few gifts from your friends, do you want to take a look?");
dialog.OnComplete += OnPromptGiftDialogClose;

 

If the play wants to accept decline request, now we can bring up Google Play Requests Accept Dialog and find out what requests were accepted. The following snippet will show an implementation example:
 

private void OnPromptGiftDialogClose(AndroidDialogResult result) {
	//parsing result
	switch(result) {
	case AndroidDialogResult.YES:
		GooglePlayManager.ActionGameRequestsAccepted += OnGameRequestAccepted;
		GooglePlayManager.Instance.ShowRequestsAccepDialog();
		break;
	}
}


private void OnGameRequestAccepted(List<GPGameRequest> gifts) {
    GooglePlayManager.ActionGameRequestsAccepted -= OnGameRequestAccepted;
	foreach(GPGameRequest g in gifts) {
		AndroidNative.showMessage("Gift Accepted", g.playload + " is accepted");
	}
}

 

We can also find out when Inbox dialog was dissmised by subscribing to the ActionRequestsInboxDialogDismissed  action.

public static Action ActionRequestsInboxDialogDismissed = delegate {};

 

The example of full using the API  example can be found under the PlayServiceExample.cs script.