Facebook Games

Cross Play

This feature is no longer available for new submissions. This documentation is intended solely for developers with existing games.

Enable Cross Play between an Instant Game and the native version of that same game allows players to share features across versions of a game and pick up where they last left off in a game regardless of which version of the game that they were playing.

Other documentation for Cross Play:

Terminologies

  • App-Scoped User ID: ID issued by Graph API for each user as the unique identifier, also called ASID.
  • Instant Game Player ID: ID issued by Instant Game SDK for each user as the unique identifier. Note that Instant Game Player ID and ASID are different even for the same user of same app.

Graph APIs (for native games)

After your native games is integrated with Facebook Login for Gaming, you will get back an access token for Gaming Graph Domain (the token starts with ‘GG’ prefix). With that token, you can access the following graph APIs offered by Cross Play.

1. Getting Users’s Instant Game Player ID

GET graph.fb.gg/{user-id}?fields=instant_game_player_id

Requirements:

  • This API is used to link user’s account between Instant game and native game based on same Application ID.
  • If your Instant Game and native games are based on different App IDs, use ids_for_business API instead.
  • It supports user access token and app token.

Response:

  • It returns the Instant Game Player ID of the current user. If user does not play Instant Game, a player ID will be generated for that user, which will persist if user plays Instant Game later on.
    {
      "id": "1234567890",
      "instant_game_player_id": "890123456"
    }

2. Getting Users’s App-Scoped User ID and Instant Game Player ID across apps

GET graph.fb.gg/{user-id}/ids_for_business

Requirements:

  • This API is used link user’s account between Instant game and native game based on different Application IDs.
  • Both Instant Game and native game’s App IDs need to connect to a common business account.
  • If your Instant Game and native games are based on same App IDs, use /{user-id}?field=instant_game_id API instead.
  • It supports user access token and app token.

Response:

  • It returns the App-Scoped User ID and Instant Game Player ID (if applicable) of the different applications under the same business account, with different types of IDs identified by the user_id_type field.
    {
      "data": [
        {
          "app": {
            "name": "My Native Game",
            "id": "11223344"
          },
          "user_id_type": "platform",
          "id": "890123456"
        },
        {
          "app": {
            "name": "My Instant Game",
            "id": "44332211"
          },
          "user_id_type": "instant_game",
          "id": "890654321"
        },
      ]
    }

3. Getting/Setting Users’s Instant Game Data

Getting Data

GET graph.fb.gg/{user-id}/data

Requirements:

  • This API is the equivalent Graph API of Instant Game SDK getDataAsync() function. It reads the same copy of data you saved for the same player on Instant Game. With this Graph API, you can sync the data between different platforms for same player.
  • It supports only user access token for now, with app token support be added soon.

Response:

  • It returns the same copy of data - a key-value store - saved for this player on Instant Game.
    {
      "data": [
        {
          "key": "achievements",
          "value": "[\"medal1\",\"medal2\",\"medal3\"]"
        },
        {
          "key": "currentLife",
          "value": "300"
        },
      ]
    }

Setting Data

POST graph.fb.gg/{user-id}/data

Requirements:

  • This API is the equivalent Graph API of Instant Game SDK setDataAsync() function. It writes to the same copy of data you saved for the same player on Instant Game. With this Graph API, you can sync the data between different platforms for same player.
  • It supports only user access token for now, with app token support be added soon.

Payload:

  • The API allows sending a payload object, in a similar fashion with another Instant SDK API switchGameAsync(), this payload is json-encoded and delivered to the native game when it’s launched. 
curl -X POST https://graph.fb.gg/{user-id}/data -d "payload={currentLife:350}"

Response:

  • If the payload is properly formatted JSON and can be deserialized correctly, it returns the status after write is conducted
    {
      "success": true
    }

Instant Game SDK

To access the new features and APIs from Instant Game SDK, you need to first import the Cross Play Beta version of Instant Game SDK in your game:

<script src="https://connect.facebook.net/en_US/fbinstant.beta-xplay.js"></script>

1. Connecting Users with ASID

FBInstant.player.getASIDAsync(): Promise<void>
  • It returns the App Scoped ID of the current user. If user does not have App Scoped ID, a new one will be generated, which will persist if user plays native version of game later on.

Requirements:

  • This API is used to link user’s account between Instant game and native game based on same Application ID.
  • If your Instant Game and native games are based on different App IDs, use ids_for_business Graph API instead.

2. Performing Graph API calls from Instant Game

/*
 * Performs a graph API Call and returns the result.
 * @param {string} path The graph API path to perform the request against.
 * @param {?string} method HTTP method that will be used for this request. GET
 * is the default if not specified.
 * @param {?Object} params Parameters that will be sent as part of the request.
 * @return {Promise} the result of the graph API call. 
 */
FBInstant.graphApi.requestAsync(
    path: string,
    method: ?string, 
    params: ?Object): Promise<Object>

Requirements:

  • This feature requires Gaming Login on Instant Game. We are currently in the process of rolling it out to all cross play enabled titles. As developer, you should have received Gaming Login on Instant Game - you can tell by seeing the button on TOS screen that says “Continue with Facebook”, instead of “Play Now”.
  • For Instant Games that enabled Gaming Login, an access token will be generated when game is loaded. This access token is managed by the Instant Game SDK and thus you will not need to manage it explicitly.
  • For example, to use Graph API to query the information of current player using /me endpoint:
FBInstant.graphApi.requestAsync('/me').then(response => {
        console.log(JSON.stringify(response));
    });

3. Navigate from Instant Game to native game

FBInstant.canSwitchNativeGameAsync(): Promise<bool>
FBInstant.switchNativeGameAsync(data?: ?Object): Promise<void>
  • This API let Instant Game players on Android/iOS seamlessly navigate to native version of the same game if it’s installed, otherwise they will be directed to the relevant store for the platform (App Store, Play Store). If the switch fails then the promise will be rejected.

Requirements:

  • We are running A/B test to assess behavior differences of users who are exposed to this navigation vs not. Thus, you should call canSwitchNativeGameAsync() first and only prompt users for navigation if response is true.

  • For this API to work the game needs to have their Android/iOS apps to use the same Facebook AppID and the native settings configured in the developer portal.

  • Android:

  • iOS:

Payload:

  • The API allows sending a payload object, in a similar fashion with another Instant SDK API switchGameAsync(), this payload is json-encoded and delivered to the native game when it’s launched.

Android - Available in the FB Android SDK v9.1 and newer.

 import com.facebook.gamingservices.GamingPayload;
 
 @Override
  protected void onStart() {
    super.onStart();
    // call this during onStart() so that it works for Cold Starts as well as
    // app switches when your app is already open.
    
    // NOTE: For Cloud Games, GamingPayload will be loaded internally when you call
    // CloudGameLoginHandler.init()
    GamingPayload.loadPayloadFromIntent(getIntent());
    
    // Once the payload has been retrieved either from the Intent or From Cloud,
    // you can get the GameRequest ID and Payload using:
    Log.e(TAG, "Game Request ID: " + GamingPayload.getGameRequestID());
    Log.e(TAG, "Payload: " + GamingPayload.getPayload());
    
    // You can now redirect the User to the appropriate screen within your game to
    // complete the action they were invited to do.
  }

iOS - Available in the FB iOS SDK v9.2 and newer.

  • GamingPayloadDelegate.h
#import <FBSDKGamingServicesKit/FBSDKGamingServicesKit.h>
#import "Console.h"

@interface GamingPayloadDelegate : NSObject <FBSDKGamingPayloadDelegate>
@end

        * GamingPayloadDelegate.m

#import "GamingPayloadDelegate.h"

@implementation GamingPayloadDelegate

- (void)updatedURLContaining:(FBSDKGamingPayload *)payload
{
  ConsoleLog(@"payload: %@", payload.payload);
  ConsoleLog(@"game request ID: %@", payload.gameRequestID);
}

@end
  • View Controller
#import <FBSDKGamingServicesKit/FBSDKGamingServicesKit.h>
#import "GamingPayloadDelegate.h"
    
- (void)viewDidLoad
{
  [super viewDidLoad];

  self.payloadDelegate = [GamingPayloadDelegate new];

  GamingServicesRegisterCells(self.tableView);
  FBSDKGamingPayloadObserver.shared.delegate = self.payloadDelegate;
}

- (void)viewWillDisappear:(BOOL)animated
{
  FBSDKGamingPayloadObserver.shared.delegate = nil;
}