Configuring Game center activities

Setup and configure a way for players to compete on a specific task or part of your game.

Overview

Use the activities API to create and configure ways to link players directly to content in your game. Once you create an activity you can link it to a challenge. To learn more about challenges, see Configuring Game Center challenges.

Activities provide a way to link players directly to your content. By describing your gameplay with activities, you can link the player to that part of your game when they engage with the activity. For example, when a player wants to complete your daily puzzle, you can send the player directly to that part of your game. To learn more about deep links, see Creating activities for your game.

Before you begin creating your activities, you need these items:

Game center enable in your binary
Game Center detail enabled

Create the activity

Begin creating the activity by using the Create an activity endpoint. Provide these attributes in your payload:

referenceName: A 40 character or less alphanumeric string.
vendorIdentifier: A reverse url scheme label for this activity.

Additionally provide a relationship to a gameCenterDetail or a gameCenterGroup. If your leaderboard is in a Game Center group, use gameCenterGroup. If you’re relating this activity to a Game Center group, you need to use the grp. prefix.

When you create an activity you use a payload like this:

{
  "data": {
    "type": "gameCenterActivities",
    "attributes": {
      "referenceName": "string",
      "vendorIdentifier": "string",
      "minimumPlayersCount": 1,
      "maximumPlayersCount": 8,
      "supportsPartyCode": false
    },
    "relationships": {
      "gameCenterDetail": {
        "data": {
          "type": "gameCenterDetails",
          "id": "string"
        }
      }
    }
  }
}

In the response you get an id in the top-level data object. This id represents the Game Center activity. You can find this id at anytime using List all activities for a Game Center detail or List all activities for a Game Center group for a grouped app.

Create the activity version

You next need to create a version for your Game center activity. The version is the parent object for localizations, the fallbackUrl and the activity image. Create the activity version using Create an activity version. The fallbackUrl is what the system uses to support operating systems before iOS 26, macOS 26, and tvOS 26, to direct a player to an invitation page on the web. To learn more about deep links and fallbackUrl, see Creating activities for your game.

{
  "data": {
    "type": "gameCenterActivityVersions",
    "attributes": {
      "fallbackUrl": "string"
    },
    "relationships": {
      "activity": {
        "data": {
          "type": "gameCenterActivities",
          "id": "string"
        }
      }
    }
  }
}

Add an activity version localization

You next add an activity version localization by using Add an activity localization. The locale and name attributes are required. The name represent the label shown for the activity inside the Games app. For a list of possible locale values, see Managing metadata in your app by using locale shortcodes. The description attribute is optional but can help a player better understand the activity. The localization requires a relationship to its parent activity version. At minimum, one activity version localization is required for submission to review.

Use a payload like this:

{
"data": {
  "type": "gameCenterActivityLocalizations",
  "attributes": {
    "locale": "string",
    "name": "string",
    "description": "string"
  },
  "relationships": {
    "version": {
      "data": {
        "type": "gameCenterActivityVersions",
        "id": "string"
      }
    }
  }
}
}

Add the activity version image

Adding a default activity image is very similar to adding an app store screenshot or app review image. You can associate the activity version default image with an activity version or an activity localization. When you create a new activity version, the default image is inherited. At minimum, a default image is required for submission to review.

Start by using Create an activity image with a payload that looks like this:

{
  "data": {
    "type": "gameCenterActivityImages",
    "attributes": {
      "fileSize": 0,
      "fileName": "string"
    },
    "relationships": {
      "version": {
        "data": {
          "type": "gameCenterActivityVersions",
          "id": "string"
        }
      }
    }
  }
}

The response includes one or more PUT requests; use these URL’s to upload your image.

After uploading, use Commit an image for an activity to commit your image to the related resource with a payload like this:

{
  "data": {
    "type": "gameCenterActivityImages",
    "id": "string",
    "attributes": {
      "uploaded": true
    }
  }
}

To learn more uploading images, see Uploading Assets to App Store Connect.

Relate your activity to a leaderboard

If your activity is not a multiplayer activity, it must be have a relationship to a leaderboard. If you don’t have an existing or appropriate leaderboard for your activity, you can create one using Create a leaderboard. A multiplayer activity, using the supportsPartyCode attribute, can be used as a lobby for a group game session. When you’re ready to relate your activity to your leaderboard, use PATCH /v1/gameCenterLeaderboards/{id}/relationships/activity with the Game Center leaderboard id in the request URL and with a payload like this:

{
  "data": {
    "type": "gameCenterActivities",
    "id": "string"
  }
}

Submit your activity version for review

Now, you’re ready to submit your activity version for review. Use Add an activity version release to attach your activity version to a gameCenterDetail. To find the gameCenterDetail id, use Read the state of Game Center for an app. Then, use Create a review submission to send the appStoreVersion, and your associated activity version to app review.