<!--
{
  "documentType" : "article",
  "framework" : "AppStoreConnectAPI",
  "identifier" : "/documentation/AppStoreConnectAPI/configuring-game-center-activities",
  "metadataVersion" : "0.1.0",
  "role" : "article",
  "title" : "Configuring Game center activities"
}
-->

# Configuring Game center activities

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

## Discussion

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](/documentation/AppStoreConnectAPI/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](https://developer.apple.com/documentation/gamekit/creating-activities-for-your-game#Add-universal-link-support).

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`](/documentation/AppStoreConnectAPI/POST-v1-gameCenterActivities) 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:

```json
{
  "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`](/documentation/AppStoreConnectAPI/GET-v1-gameCenterDetails-_id_-gameCenterActivities) or [`List all activities for a game center group`](/documentation/AppStoreConnectAPI/GET-v1-gameCenterGroups-_id_-gameCenterActivities) 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`](/documentation/AppStoreConnectAPI/POST-v1-gameCenterActivityVersions). 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](https://developer.apple.com/documentation/gamekit/creating-activities-for-your-game#Add-universal-link-support).

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

> Note: The system uses the activity version `id` in this response in the version localization, so this `id` is  a possible relationship to the activity image.

### Add an activity version localization

You next add an activity version localization by using [`Add an Activity Localization`](/documentation/AppStoreConnectAPI/POST-v1-gameCenterActivityLocalizations). 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](/documentation/AppStoreConnectAPI/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:

```json
{
"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`](/documentation/AppStoreConnectAPI/POST-v1-gameCenterActivityImages) with a payload that looks like this:

```json
{
  "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`](/documentation/AppStoreConnectAPI/PATCH-v1-gameCenterActivityImages-_id_) to commit your image to the related resource with a payload like this:

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

To learn more uploading images, see [Uploading Assets to App Store Connect](/documentation/AppStoreConnectAPI/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`](/documentation/AppStoreConnectAPI/POST-v1-gameCenterLeaderboards). 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 [`Modify the activity for a Game Center leaderboard`](/documentation/AppStoreConnectAPI/PATCH-v1-gameCenterLeaderboards-_id_-relationships-activity) with the Game Center leaderboard `id` in the request URL and with a payload like this:

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

### Submit your activity version for review

> Note: One localization and a default image are required for submission.

Now, you’re ready to submit your activity version for review. Use [`Add an Activity Version Release`](/documentation/AppStoreConnectAPI/POST-v1-gameCenterActivityVersionReleases) to attach your activity version to a `gameCenterDetail`. To find the `gameCenterDetail` id, use [`Read the state of game center for an app`](/documentation/AppStoreConnectAPI/GET-v1-apps-_id_-gameCenterDetail). Then, use [`Create a Review Submission`](/documentation/AppStoreConnectAPI/POST-v1-reviewSubmissions) to send the `appStoreVersion`, and your associated activity version to app review.

Use a payload like this:

```json
{
  "data": {
    "type": "gameCenterActivityVersionReleases",
    "relationships": {
      "gameCenterDetail": {
        "data": {
          "type": "gameCenterDetails",
          "id": "string"
        }
      },
      "version": {
        "data": {
          "type": "gameCenterActivityVersions",
          "id": "string"
        }
      }
    }
  }
}
```

> Tip: Read a list of the past activity version releases using ``doc://com.apple.appstoreconnectapi/documentation/AppStoreConnectAPI/GET-v1-gameCenterDetails-_id_-activityReleases``. Use the optional include `version` to get more details and to read the `id` of the Game Center activity version that is currently `LIVE`.

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)