App and Game Groups

Apps and games can now create and manage Groups via the Graph API to help people connect and share their experiences.

Groups are a natural fit for games. Many games organize their players into clans, alliances, teams or other types of groups to accomplish tasks within the game. Gamers already create their own Groups to hang out with other players, share information about the game, and make plans to collaborate in-game.

People who interact more with other players will be more invested in the game, play longer and are more likely to pay.

We will refer to the feature as "Game Groups" going forward in this document.

This document walks through

• Benefits
• Design Overview
• User Experience
  • Creating groups
  • Viewing and Joining Groups in the Game
  • Adding Players to Groups
  • Administering Groups
  • Viewing the Group on Facebook
  • Posting to Groups from Games
  • Creating Events from Games
• Implementation Details

Benefits

• Access to social channels. Game Groups can access the same social channels as regular Facebook Groups–bookmarks, notifications, and calendar reminders— increasing the likelihood people will come back to engage with your game’s community.

• Making games more social. Game Groups add another social layer to games by allowing people to collaborate, share and express their gamer identity with other players.

• Engaging & retaining players. Game Groups facilitate community interaction and drive deeper connections among players, leading to more engaged players who play longer.

Design Overview

Developers can use Game Groups to build a group experience right into their game. We’ve built a set of APIs that enable games to create groups and manage membership.

Players in a Game Group can also interact outside of the game. A bookmark to the Game Group will appear in the person's navigation area. These groups are special Facebook Groups that belong to a game.

Games can integrate with groups from within the game. Players can post into the group from within the game. This is useful for sharing screenshots or screencasts. Players can also create events from within the game. These will appear as group events on Facebook.

User Experience

Creating Groups

Players may want to create their own group. Games can have players provide parameters like name, description and privacy. Games should consider making the creator of the group the default administrator which can be done in the group creation call. The privacy setting can be used to control who sees the group.

Viewing and Joining Groups in the Game

Games should build an interface where players can view groups. When a player views a group, games can list which members are in a specific group. Games can also list the groups that a player belongs to.

After viewing a group, a player may want to join. Games should provide browse or search functionality to help players find groups. Games could also suggest groups for the player to join in order to optimize the game experience (for example, based on geographical location or skill level).

Games need to create a request and approve flow for users to be added to groups. Usually there are 2 kinds of flows for users to be added to groups.

In one flow, players find a group they want to join and request to join. The request is sent to the admin and they approve or deny the join request. In the second flow, admins invite players to join they group. The player receives the invite and then approves or denies being added to the group.

You must build this flow into your game. You can use App Notifications or Requests to message a player or admin that a join request has been sent.

This is an example of using App Notifications to message to the user that they've been invited to the group.

Adding Players to Groups

When you want to add the player to the group (after the admin and player has approved), you can call the add api. When the player has been added to the group, a notification will be sent to the user that the player has been added. The notification will look like it came from the game.

The notification can also be sent on behalf of a person which causes the notification to look like it came from the person instead of the game.

When players click this notification they will be taken to the group page.

Administering Groups

Groups usually have an administrator that have special abilities. If a group is being created by a player, the game should consider making them an admin. A parameter can be passed during group creation to accomplish this.

Games should build a request mechanism for members who want to join groups that are closed or secret. Admins usually manage these requests.

Admins have the ability to set the cover photo. Games can help admins personalize their groups by providing a way to use in-game content as a cover photo.

Game can also help admins control their group by exposing the functionality to remove members and promote other members to admins.

Viewing the Group on Facebook

After a player joins a group, a bookmark to the group will appear in their navigation area.

Posting to Groups from Games

With Game Groups, games can post stories to groups from the game. This creates a way for players to share game content into their group and keep players engaged with the game. Players will see notifications when content is shared.

Players can also navigate back to the group via a bookmark that appears in the navigation area.

The player is prompted to share a screenshot of his base from the game to his clan.

The story has been shared in the group. Also note that bookmarks are generated for Game Groups.

Members of the group will receive notifications when content is shared in the group.

Creating Events from Games

Games can bring players back into the game by creating group events. The current list of events for a group can be retrieved.

When group members are invited to an event, a notification will appear.

Group events will appear as calendar notifications.

Implementation Details

App and Game Groups uses a number of different objects across the Graph API. This page aggregates all those calls into a single reference so you can easily understand where to find various calls.

Features

App and Game Groups is designed so that apps can create and manage groups to help people connect and share their experiences. One of the main use cases for Groups is games, which already organize their players into groups through clans, alliances, guilds or other game communities. For this reason, we will refer to the feature as "Game Groups" going forward in this document.

This feature exposes an API to do the following:

• Get all groups that belong to a game.
• Get all groups a user belongs to in a game.
• Create and Delete a group.
• Get all members of a group.
• Add and Remove a user to/from the group.
• Promote and Remove group admins.
• Post stories to the group feed
• Create and Get events for the group.
• Set the cover photo for the group.

Game Groups have a privacy setting which controls who sees the group.

• Open (public) groups: Anyone can see the group, who's in it and what members post.
• Closed groups: Anyone can see the group and who's in it but only members can see posts.
• Secret groups: Only members see the group, who's in it and what members post.

API Details

Game Groups

Game Groups are created and controlled by the application.

Read All Groups

Applications can get all the groups that belong to an application by issuing a GET request to /APP_ID/groups with an app access_token.

If the action is successful, the response will be an array that contains elements with the following properties:

Name	Description	Type
id	The id of the group.	string
name	The name of the group.	string

Read User Groups

Applications can get all the groups a user belongs in an application by issuing a GET request to /me/groups?parent=APP_ID with a user access_token. This requires the user_groups permission.

If the action is successful, the response is an array in which each element contains:

Name	Description	Type
id	The id of the group.	string
name	The name of the group.	string
administrator	The user is administrator of the group. This field will only be returned if the user is an administrator.	boolean

Create

Applications create a group issuing a POST request to /APP_ID/groups with an app access_token. Optionally, a user can be set as an admin of a group by setting the admin parameter.

Parameter	Description	Type	Required
name	A name for the group.	string	yes
description	A description for the group.	string	no
privacy	The privacy setting for the group.	string (open, closed, secret)	no (default: closed)
admin	The user ID of the admin.	string	no

If the action is successful, the response will contain:

Name	Description	Type
id	The id of the group.	string

Delete

Applications delete a group issuing a DELETE request to /APP_ID/groups/GROUP_ID with an app access_token. If the group has no members, the group will be irreversibly deleted. If the group has members, the group will no longer be associated with the application and become a normal Facebook Group.

If the action is successful, the response will contain true.

Members

Read

Applications can get the list of members that belong to a group by issuing a GET request to /GROUP_ID/members with an app access_token.

If the action is successful, the response will contain:

Name	Description	Type
id	The id of the user.	string
name	The name of the user.	string
administrator	The user is administrator of the group.	boolean

Add User to Group

Applications can add users to a group by issuing a POST request to /GROUP_ID/members/USER_ID with an app access_token.

Note that user being added must be a user of the application. The user will be sent a notification saying that they have been "invited" to the group. The notification will take them to the group page. Users can only be added once. Subsequent adds will fail.

Optionally, a from parameter can be passed in the request. If the from parameter is included, then the add notification will look like it was sent by the from user. If this parameter is not included, then the add notification will appear to come from the application. Add notifications sent on behalf of a user can only be sent to the sender's friends.

Parameter	Description	Type	Required
from	The ID of the user doing the adding.	string	no

If the action is successful, the response will contain true.

Remove Member

Users can be removed from a group by issuing a DELETE request to GROUP_ID/members/USER_ID with an app access_token.

If the action is successful, the response will contain true.

Promote Admin

A member of a group can be promoted to admin by issuing a POST request to /GROUP_ID/admins/USER_ID with an app access_token. The user must be a member of the group. The user will receive a notification that they have been made an admin for the group.

If the action is successful, the response will contain true.

Remove Admin

A member of a group can be promoted to admin by issuing a DELETE request to /GROUP_ID/admins/USER_ID with an app access_token.

If the action is successful, the response will contain true.

Customize Groups

Post to Feed

Users can post a link on the Group's wall by issuing an HTTP POST request to /GROUP_ID/feed with the publish_actions permissions and the following parameters. This requires a user access_token.

Parameter	Description	Type	Required
message	Post message	string	either message or link
link	Post URL	string	either message or link
picture	Post thumbnail image (can only be used if link is specified)	string	no
name	Post name (can only be used if link is specified)	string	no
caption	Post caption (can only be used if link is specified)	string	no
description	Post description (can only be used if link is specified)	string	no

If the create is successful, the response will contain:

Name	Description	Type
id	The new post ID	string

Users can post a photo to the Group feed by issuing an HTTP POST request to /GROUP_ID/photos with the following parameters. This requires a user access_token. Read more about the photos api.

Parameter	Description	Type	Required
image	Photo to be shared.	file contents	yes
message	Post message	string	no
tags	Tagged users and their positions in the photo. This must be an array of objects. Each object must have: `x` coordinate (percentage from left), `y` coordinate (percentage from top) and `tag_uid` for the tagged user.	array	no

If the create is successful, the response will contain:

Name	Description	Type
id	The ID of the photo	string
post_id	The ID of the post	string

Set Cover Photo

Applications can set the cover photo for a group by issuing a POST request to /GROUP_ID with an app access_token.

Name	Description	Type	Required
cover_url	The url for the cover photo. The image will be downloaded and added to the group's album and then used as a cover photo.	string	yes

If the action is successful, the response will contain true.

Get Events

Applications can get events for a group by issuing a GET request to /GROUP_ID/events with a user access_token.

If the action is successful, the response will contain:

Name	Description	Type
id	The id of the event.	string
name	The name of the event	string
start_time	Start time of the event in ISO-8601 format.	string
end_time	End time of the event in ISO-8601 format.	string
location	Location of the event.	string

Create Event

Users can create an event for a group by issuing a POST request to /GROUP_ID/events with a user access_token. The user needs the create_event permission.

All event times are ISO-8601 formatted strings (e.g., '2012-07-04', '2012-07-04T19:00:00-0700'). Event times containing the time must have the UTC offset.

Parameter	Description	Type	Required
name	Name of event.	string	yes
start_time	Start time of the event in ISO-8601 format.	string	yes
end_time	End time of the event in ISO-8601 format.	string	no
description	Description of the event.	string	no
location	Location of the event.	string	no
location_id	Facebook Place ID of the place for the event.	string	no

If the create is successful, the response will contain:

Name	Description	Type
id	The new event ID	string

Next Steps

To learn about other ways to drive distribution for your Game please refer to the Games distribution doc.