Uploading and versioning Apple hosted background assets

Overview

Use the Background assets API to manage content that Apple hosts, so people can download that content outside your main app bundle, for apps distributed through the App Store. You can also update additional content without creating a new app version.

Create an asset pack record

Once you create your asset pack, you can start configuring your Apple hosted background assets. Begin by using Create asset pack record.

In the request body, add the name of the asset pack as the assetPackIdentifier and add your app’s Apple ID In the relationships section.

This sample payload shows the structure of a Create asset pack record request:

{
  "data": {
    "type": "backgroundAssets",
    "attributes": {
      "assetPackIdentifier": "Tutorial"
    },
    "relationships": {
      "app": {
        "data": {
          "type": "apps",
          "id": "123456789"
        }
      }
    }
  }
}

This call’s response returns a UUID to your asset pack, which you can use in later API calls.

Create an asset pack version record

Next, you create a new version for your asset pack by using Create asset pack version record. In the relationships section, use the ID of the asset pack that the previous API response returned.

{
  "data": {
    "type": "backgroundAssetVersions",
    "relationships": {
      "backgroundAsset": {
        "data": {
          "type": "backgroundAssets",
          "id": "1930fc63-0466-4a4a-bcfd-e0a3cc7a341a"
        }
      }
    }
  }
}

Upload an asset pack archive

This process is similar to uploading screenshots or app previews. First, you use Create a reservation for an asset pack upload with a payload like this, where you use the UUID from the response when using Create asset pack version record:

{
  "data": {
    "type": "backgroundAssetUploadFiles",
    "attributes": {
      "assetType": "ASSET",
      "fileName": "Tutorial.aar",
      "fileSize": 59587
    },
    "relationships": {
      "backgroundAssetVersion": {
        "data": {
          "type": "backgroundAssetVersions",
          "id": "5934fd14-5123-gbgb-9090-01a2GYhg213z"
        }
      }
    }
  }
}

You can optionally upload the asset manifest, to check its validity, by using Create a reservation for an asset pack upload before you upload your full asset pack. The system checks the validity of your manifest and returns an error, if there is an issue. Use a payload like this to verify your manifest:

{
  "data": {
    "type": "backgroundAssetUploadFiles",
    "attributes": {
      "assetType": "MANIFEST",
      "fileName": "Manifest.json",
      "fileSize": 9675
    },
    "relationships": {
      "backgroundAssetVersion": {
        "data": {
          "type": "backgroundAssetVersions",
          "id": "5934fd14-5123-gbgb-9090-01a2GYhg213z"
        }
      }
    }
  }
}

Then, you upload the file with PUT request or requests, as necessary, which are included in the response of Create a reservation for an asset pack upload.

Commit your asset pack to begin processing

When you successfully upload your archive, you use Commit an uploaded asset pack to a background asset version to commit the upload. After this call, your upload starts processing. Use a payload like this including the upload file ID:

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

Test your asset pack

When the asset pack version is successfully processed by the App Store, you see an Internal Beta Release resource created with the “Ready for testing” state in App Store Connect. This means the new version is ready for use in your app builds in internal TestFlight.