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

# Configuring Game Center challenges

Setup and configure social experiences around leaderboards for friendly competition.

## Discussion

Use the challenges API to create and configure ways to link players directly to your content in your game. Once you create a challenge, you can link it an activity, by relating the activity to the challenge’s leaderboard. To learn more about activities, see [Configuring Game center activities](/documentation/AppStoreConnectAPI/configuring-game-center-activities).

Challenges encourage your players to invite their friends into your game for friendly competitions in score-based rounds. Players will see challenges promoted throughout the Games app and other places around the OS as suggestions for enjoying their games with friends. They can invite their Game Center friends and anyone from their contacts, see scores appear in real-time, get notified at key moments until a winner is crowned, and have a rematch. Challenges are built on top of leaderboards, turning single-player game activities into a social experience players can share with their friends.

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

- An approved or draft leaderboard for your game
- Game Center enabled in your binary
- Game Center detail enabled

### Create the challenge

Begin creating the challenge by using the [`Create a Challenge`](/documentation/AppStoreConnectAPI/POST-v1-gameCenterChallenges) endpoint. Provide these attributes in your payload:
-`referenceName`: A 40 character or less alphanumeric string.
-`vendorIdentifier`: A reverse url scheme label for this challenge.
-`challengeType`: This value is always the string `leaderboard`.
-`allowedDurations`: Use all 3 values for this attribute. If the related leaderboard is reoccurring, omit this attribute.

Additionally provide:

- A relationship to a `leaderboard`
  - Obtain the leaderboard resource ID from the [`List Leaderboards`](/documentation/AppStoreConnectAPI/GET-v1-gameCenterDetails-_id_-relationships-gameCenterLeaderboards) or [`Read the Leaderboards in a Group`](/documentation/AppStoreConnectAPI/GET-v1-gameCenterGroups-_id_-relationships-gameCenterLeaderboards) response.
- A relationship to a `gameCenterDetail` or a `gameCenterGroup`
  - If your leaderboard is in a Game Center group, use `gameCenterGroup`.
  - If you’re relating this challenge to a Game Center group, you need to use the `grp.` prefix.

When you create a challenge you use a payload like this:

```json
{
  "data": {
    "type": "gameCenterChallenges",
    "attributes": {
      "referenceName": "string",
      "vendorIdentifier": "string",
      "allowedDurations": [
        "ONE_DAY","THREE_DAYS","ONE_WEEK"
      ],
      "challengeType": "LEADERBOARD",
      "repeatable": false
    },
    "relationships": {
      "gameCenterDetail": {
        "data": {
          "type": "gameCenterDetails",
          "id": "string"
        }
      },
      "leaderboard": {
        "data": {
          "type": "gameCenterLeaderboards",
          "id": "string"
        }
      }
    }
  }
}
```

In the response you get an `id` in the top-level data object. This `id` represents the Game Center challenge. You can find this `id` at anytime using [`Read the challenges for a game center detail`](/documentation/AppStoreConnectAPI/GET-v1-gameCenterDetails-_id_-gameCenterChallenges).

### Create the challenge version

Next, you need to create a version for your Game Center challenge. The version is the parent object for localizations and the challenge default image. Create the challenge version using [`Create a Challenge Version`](/documentation/AppStoreConnectAPI/POST-v1-gameCenterChallengeVersions).

```json
{
  "data": {
    "type": "gameCenterChallengeVersions",
    "relationships": {
      "challenge": {
        "data": {
          "type": "gameCenterChallenges",
          "id": "string"
        }
      }
    }
  }
}
```

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

### Add a challenge version localization

You next add a challenge version localization by using [`Add a Challenge Localization`](/documentation/AppStoreConnectAPI/POST-v1-gameCenterChallengeLocalizations). 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 challenge. The localization requires a relationship to its parent challenge version. At minimum, one challenge version localization is required for submission to review.

Use a payload like this:

```json
{
  "data": {
    "type": "gameCenterChallengeLocalizations",
    "attributes": {
      "locale": "string",
      "name": "string",
      "description": "string"
    },
    "relationships": {
      "version": {
        "data": {
          "type": "gameCenterChallengeVersions",
          "id": "string"
        }
      }
    }
  }
}
```

### Add the challenge version image

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

Start by using [`Create a Challenge Image`](/documentation/AppStoreConnectAPI/POST-v1-gameCenterChallengeImages) with a payload that looks like this:

```json
{
  "data": {
    "type": "gameCenterChallengeImages",
    "attributes": {
      "fileSize": 0,
      "fileName": "string"
    },
    "relationships": {
      "version": {
        "data": {
          "type": "gameCenterChallengeVersions",
          "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 a Challenge`](/documentation/AppStoreConnectAPI/PATCH-v1-gameCenterChallengeImages-_id_) to commit your image to the related resource with a payload like this:

```json
{
  "data": {
    "type": "gameCenterChallengeImages",
    "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).

### Submit your challenge version for review

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

Now, you’re ready to submit your challenge version for review. Use [`Add a Challenge Version Release`](/documentation/AppStoreConnectAPI/POST-v1-gameCenterChallengeVersionReleases) to attach your challenge 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 challenge version to app review.

Use a payload like this:

```json
{
  "data": {
    "type": "gameCenterChallengeVersionReleases",
    "relationships": {
      "gameCenterDetail": {
        "data": {
          "type": "gameCenterDetails",
          "id": "string"
        }
      },
      "version": {
        "data": {
          "type": "gameCenterChallengeVersions",
          "id": "string"
        }
      }
    }
  }
}
```

> Tip: You can read a list of the past challenge version releases and their states using ``doc://com.apple.appstoreconnectapi/documentation/AppStoreConnectAPI/GET-v1-gameCenterDetails-_id_-challengeReleases``. Use the optional include `version` to get more details and to read the `id` of the Game Center challenge 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)