App and Game Groups (Deprecated)

Overview

App and Game Groups are deprecated. API access for new apps will be closed on May 1, 2016. Game and App Groups will be deprecated for all apps on October 17, 2016.

App and Game Groups give games the ability to integrate Facebook Groups into their game. With this feature, games can gather players into groups, give them a space for sharing and build engaging group experiences.

This feature is a natural fit for games that have clans, alliances, teams, VIPs or other types of groups. Players who participate in groups are often the most valuable players who retain the best and monetize the most. With Game Groups, you can help grow this set of players.

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

This document walks through:

Version 2 of Game Groups contains some changes to the user flow as well as deprecated functionality. Please see the Change Log to find more details and be sure to make sure your app is compliant if you are moving from Version 1 to Version 2.


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 and monetize more.

Design Overview

Developers can use Game Groups to build a group experience right into their game. We’ve built a set of APIs and dialogs that enable games to create groups, manage membership and facilitate sharing. These features are available for Facebook Web Games and mobile games.

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.

Please note the policy rules throughout this document to ensure you are incorporating Game Groups appropriately.


User Experience

Creating Groups

The first step in integrating groups into your game is giving players the ability to create their own group. With this feature you can set parameters like name, description and privacy. You should also consider making the creator the default admin.

Policy: When a player is creating a Game Group there must be explicit messaging in the UI which communicates that the player is also creating a Facebook Group.

An in-game create dialog.
Dialog for web and iOS (Android not shown).

Viewing Groups

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 is an admin of.

Joining Groups

Game Groups can have up to 10,000 members.

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).

An in-game join dialog.

Games need to create a request and approve flow for users to be added to groups. You should use in-game messaging to communicate invites and may consider using App Notifications or Requests to tell the player about outstanding requests.

Typically, there are 2 kinds of flows for users to be added to groups. In the first 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.

Using App Notifications is one way to message the user.

When you want to add the player to the group -- after the admin and player has approved --, you can show a join dialog. When they've been added, a notification will be sent to the user that the player has been added. The notification will look like it came from the game.

Dialog for web and iOS (Android not shown).
When players join a group they will get a notification.
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. 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.

Moderation

You may be concerned about negative posts in a Facebook group that may give players a bad experience. There are built-in methods for moderation. For each post, there is an option to report it to the admin of the group or report it to Facebook. When the post is reported to the admin, they will have the option to keep the post, delete the post and ban the member from the group. If the post is reported to Facebook, it will moderated by us.

Viewing the Group on Facebook

After a player joins a group, a bookmark to the group will appear in their navigation area. The bookmark is an easy way for people to return back to the group.

Posting to Groups

Game Groups provide a space where players can interact with each other or content posted from the game, keeping them engaged. Games can post stories to groups as the game or on behalf of the user. You should use the type of sharing that’s appropriate to the experience.

When games post stories as the game, the stories will look like they were posted from the app. Games can view the likes and comments on its posts by reading the feed. Some example of appropriate content would be announcements, reminders or notices. Be sure to pick use cases where it’s appropriate to use the game’s voice.

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

When games post stories on behalf of the user, the stories will look like they were posted by the user. Your game can create sharing experiences from the game into the group. When using this method, there must be explicit messaging in the UI informing the player that their content is viewable by group members. Some example of appropriate use cases would be sharing resources, achievements and requests for help.

A notification may appear when a story gets posted to the group.

Policy: When posting to a group on behalf of the user, there must be explicit messaging in the UI which communicates that players's content can be accessed by members of the group and is not restricted by their app privacy level.

The game prompts the player to share from the game to his group.
The story has been shared in the group on behalf of the user.
Groups are viewable on mobile.
Members of the group may receive notifications when content is shared in the group.

Implementation

Game Groups provides the functionality to do the following:

When your app is in development mode, Game Groups will only work for app admins, developers, testers and test users.

Building for web and mobile

Game Groups supports Facebook Web Games and mobile apps. Choose the appropriate integration based on your software architecture. API requests using app access tokens should only be made from your server and not from the client. You should never ship your client with your app access token for security reasons.

We've provided client-side dialogs so that players can create and join groups. These are available in the JS, iOS and Android SDKs.

Never put your app access token in your mobile app binary as it is a security risk. Make calls to your server or use a client-side dialog to avoid doing this.

Create Group

Apps can create a group in two different ways. They can use the API or a dialog.

Policy: When a user is creating a Game Group there must be explicit messaging in the UI which communicates that the user is also creating a Facebook 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.

Dialogs

JS SDK

FB.ui({
  method: 'game_group_create',
  name: 'My Test Group',
  description: 'A description for the test group',
  privacy: 'CLOSED',
},
 function(response) {
    if (response && response.id) {
      alert("Group was created with id " + response.id);
    } else {
      alert('There was an error creating your group.');
    }
 }
);

iOS

FBSDKAppGroupContent *appGroupContent = [[FBSDKAppGroupContent alloc] init];
   appGroupContent.name = @"The Three Musketeers";
   appGroupContent.groupDescription = @"All for one and one for all.";
   appGroupContent.privacy = FBSDKAppGroupPrivacyClosed;

   // Assuming self implements FBSDKAppGroupAddDialogDelegate
   [FBSDKAppGroupAddDialog showWithContent:appGroupContent
                                  delegate:self];

Android

CreateAppGroupDialog createAppGroupDialog;
 CallbackManager callbackManager;

 public void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     FacebookSdk.sdkInitialize(this.getApplicationContext());

     callbackManager = CallbackManager.Factory.create();
     createAppGroupDialog = new CreateAppGroupDialog(this);
     createAppGroupDialog.registerCallback(callbackManager, new FacebookCallback<CreateAppGroupDialog.Result>() {
         public void onSuccess(CreateAppGroupDialog.Result result) {
             String id = result.getId();
         }

         public void onCancel() {}

         public void onError(FacebookException error) {}
     });
 }

 private void onClickCreateButton() {
     AppGroupCreationContent content = new AppGroupCreationContent.Builder()
             .setName("A test group")
             .setDescription("A description for my group")
             .setAppGroupPrivacy(AppGroupCreationContent.AppGroupPrivacy.Closed)
             .build();
     createAppGroupDialog.show(content);
 }

 protected void onActivityResult(int requestCode, int resultCode, Intent data) {
     super.onActivityResult(requestCode, resultCode, data);
     callbackManager.onActivityResult(requestCode, resultCode, data);
 }

Add User to Group

To add a user to a group show them a join dialog. Pass in the id of the group you want the user to join. A group can have up to 10,000 members. Users can only be added once. Subsequent adds will fail.

You can also add users who have a role in the app (admins, developers, testers and test users) via API. For example, you could add a community manager as a tester to your app and then add them to groups via API.

Dialogs

JS SDK

FB.ui({
  method: 'game_group_join',
  id: '1234',
  display:'async',
}, function(response) {
  console.log(response);
  if (response.added == true) {
    alert("you've joined the group.");          
  } else {
    alert("error: " + response.error_message);
  }
});

iOS

// Assuming self implements FBSDKAppGroupJoinDialog
    [FBSDKAppGroupJoinDialog showWithGroupID:@"1234" delegate:self];

Android

CallbackManager callbackManager;

    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        FacebookSdk.sdkInitialize(this.getApplicationContext());

        callbackManager = CallbackManager.Factory.create();
        ...
    }

    private void onClickJoinButton() {
        JoinAppGroupDialog.show(this, "GROUP_ID");
    }

    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        callbackManager.onActivityResult(requestCode, resultCode, data);
    }

Post to Group Feed

There are two ways to post stories to a group's feed, depending on the use case. In the first case, apps can post as the app by API. These stories will look like they were posted by the app. In the second case, apps can post on behalf of the user by API. These stories will look like they were posted by the user.

Policy: When posting to a group on behalf of the user, there must be explicit messaging in the UI which communicates that user's content can be accessed by members of the group and is not restricted by their app privacy level.

Best Practices

Data shows that players who've joined groups are your most valuable players. They are the most engaged and best monetizing players. Typically, a player will play more frequently and monetize better after joining a group. However, your game has to build the right experiences in order to optimize player conversion.

  • Integrate sharing to group in your game - The greatest value that Game Groups provides is a space for sharing and communication on Facebook. The best way to leverage this is to create ways for players to share from your game into the group. Use best practices for sharing to create high quality stories. Considering linking stories back to your app on web or mobile.

  • Foster group adoption - Give players incentives to join groups such as extra benefits or boosts. Creating a game mechanic like sharing resources also motivated players to join groups.

  • Create competition - Appeal to player's competitive instinct. Some games use group competitions like clan wars. Another form of competition is a tournament. Consider using game events as a way to create competition on a regular basis. Events have shown to drive high engagement and monetization.

Next Steps

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