GameRequestDialog

The GameRequestDialog module allows you to display a dialog for sending game requests to Facebook friends, inviting them to play your game or sending in-game gifts.

Import

import { GameRequestDialog } from 'react-native-fbsdk-next';

Methods

canShow

Checks whether the game request dialog can be displayed.

GameRequestDialog.canShow(): Promise<boolean>

Returns a Promise that resolves to true if the dialog can be shown, false otherwise. Example:

const canShowDialog = await GameRequestDialog.canShow();

if (canShowDialog) {
  console.log('Game request dialog is available');
} else {
  console.log('Game request dialog is not available');
}

show

Displays the game request dialog with the specified content.

GameRequestDialog.show(
  gameRequestContent: GameRequestContent
): Promise<GameRequestDialogResult>

GameRequestContent

required

Configuration object defining the game request content, recipients, and behavior.

Returns a Promise that resolves to a GameRequestDialogResult object containing the request ID and recipient list.

Usage Examples

Simple Game Request

import { GameRequestDialog } from 'react-native-fbsdk-next';

const sendGameRequest = async () => {
  try {
    const result = await GameRequestDialog.show({
      message: 'Join me in this awesome game!',
    });

    if (!result.isCancelled) {
      console.log('Request sent!');
      console.log('Request ID:', result.requestId);
      console.log('Recipients:', result.to);
    } else {
      console.log('Request cancelled');
    }
  } catch (error) {
    console.log('Error showing game request dialog:', error);
  }
};

Send Request with Title

const sendInvite = async () => {
  const result = await GameRequestDialog.show({
    message: 'I need your help to complete this level!',
    title: 'Help Me Out!',
  });

  if (!result.isCancelled) {
    console.log('Invitation sent to:', result.to);
  }
};

Send Gift to Friends

const sendGift = async () => {
  const result = await GameRequestDialog.show({
    message: 'I sent you a special gift!',
    title: 'Gift for You',
    actionType: 'send',
    objectId: 'gift_12345',
    data: JSON.stringify({ type: 'gold', amount: 100 }),
  });

  if (!result.isCancelled) {
    console.log('Gift sent! Request ID:', result.requestId);
  }
};

Ask for Items

const askForHelp = async () => {
  const result = await GameRequestDialog.show({
    message: 'Can you send me some energy?',
    title: 'Need Energy',
    actionType: 'askfor',
    objectId: 'energy_item',
  });

  if (!result.isCancelled) {
    console.log('Request sent to:', result.to.length, 'friends');
  }
};

Turn-Based Game Request

const inviteToTurn = async () => {
  const result = await GameRequestDialog.show({
    message: "It's your turn to play!",
    title: 'Your Turn',
    actionType: 'turn',
    objectId: 'game_session_789',
    data: JSON.stringify({
      gameId: 'session_789',
      currentScore: 1250,
    }),
  });

  if (!result.isCancelled) {
    console.log('Turn invitation sent');
  }
};

Send to Specific Recipients

const sendToFriends = async (friendIds: string[]) => {
  const result = await GameRequestDialog.show({
    message: 'Join me in the game!',
    recipients: friendIds,
  });

  if (!result.isCancelled) {
    console.log('Sent to:', result.to);
  }
};

// Usage
sendToFriends(['user_id_1', 'user_id_2', 'user_id_3']);

Filter by App Users

const inviteAppUsers = async () => {
  const result = await GameRequestDialog.show({
    message: 'Challenge me in the arena!',
    title: 'Arena Challenge',
    filters: 'app_users', // Only show friends who use the app
  });

  if (!result.isCancelled) {
    console.log('Challenge sent!');
  }
};

Invite Non-Users

const inviteNewPlayers = async () => {
  const result = await GameRequestDialog.show({
    message: 'Try this amazing game!',
    title: 'Play With Me',
    filters: 'app_non_users', // Only show friends who don't use the app
  });

  if (!result.isCancelled) {
    console.log('Invitations sent to new players');
  }
};

With Suggested Friends

const suggestFriends = async () => {
  const result = await GameRequestDialog.show({
    message: 'Join our team!',
    title: 'Team Invitation',
    suggestions: ['user_id_1', 'user_id_2'], // Show these friends first
  });

  if (!result.isCancelled) {
    console.log('Team invitation sent');
  }
};

Complete Example with Error Handling

import React from 'react';
import { Button, Alert } from 'react-native';
import { GameRequestDialog } from 'react-native-fbsdk-next';

const GameInviteButton = () => {
  const sendInvitation = async () => {
    try {
      // Check if dialog can be shown
      const canShow = await GameRequestDialog.canShow();
      
      if (!canShow) {
        Alert.alert('Error', 'Game request dialog is not available');
        return;
      }

      // Show the dialog
      const result = await GameRequestDialog.show({
        message: 'Join me in this epic adventure!',
        title: 'Game Invitation',
        actionType: 'send',
        data: JSON.stringify({
          level: 5,
          reward: 'bonus_coins',
        }),
      });

      if (result.isCancelled) {
        console.log('User cancelled the request');
      } else {
        Alert.alert(
          'Success!',
          `Invitation sent to ${result.to.length} friend(s)`,
          [
            {
              text: 'OK',
              onPress: () => {
                // Track the request
                console.log('Request ID:', result.requestId);
                console.log('Recipients:', result.to);
              },
            },
          ]
        );
      }
    } catch (error) {
      console.error('Game request error:', error);
      Alert.alert('Error', 'Failed to send game request');
    }
  };

  return (
    <Button
      title="Invite Friends"
      onPress={sendInvitation}
    />
  );
};

export default GameInviteButton;

TypeScript Types

GameRequestContent

Configuration for a game request.

type GameRequestContent = {
  /**
   * A plain-text message to be sent as part of the request (required)
   */
  message: string;

  /**
   * Defines the nature of the request
   */
  actionType?: ActionType;

  /**
   * Additional freeform data for tracking (max 255 characters)
   */
  data?: string;

  /**
   * Controls which friends are shown in the selector
   */
  filters?: Filters;

  /**
   * Open Graph object ID being sent/asked for
   * Required if actionType is 'send' or 'askfor'
   */
  objectId?: string;

  /**
   * Array of user IDs to send requests to
   */
  recipients?: Array<string>;

  /**
   * Array of user IDs shown first in the dialog
   * Cannot be used with filters
   */
  suggestions?: Array<string>;

  /**
   * Title for the dialog
   */
  title?: string;
};

ActionType

Defines the type of game request.

type ActionType =
  | 'send'    // Sending an object to friends
  | 'askfor'  // Asking for an object from friends
  | 'turn';   // Friends' turn to play in a match

Filters

Controls which friends are displayed in the selector.

type Filters =
  | 'app_users'      // Only friends using the app
  | 'app_non_users'; // Only friends not using the app