Configuring Game Center challenges

Setup and configure social experiences around leaderboards for friendly competition.

Overview

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.

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 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 or Read the leaderboards in a group 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:

{
  "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.

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.

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

Add a challenge version localization

You next add a challenge version localization by using Add a challenge 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 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:

{
  "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 with a payload that looks like this:

{
  "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 to commit your image to the related resource with a payload like this:

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

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

Submit your challenge version for review

Now, you’re ready to submit your challenge version for review. Use Add a challenge version release to attach your challenge 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 challenge version to app review.