APKs and Tracks

The Google Play Developer API allows you to upload new APKs for your apps and release them to different release tracks. This allows you to deploy alpha and beta versions of your app, which are made available to approved users. This also allows you to deploy a staged rollout version, which is automatically made available to a small number of the app's users. Once you have released the staged rollout version, you can gradually increase the number of users who get that version of the app, until you finally deploy that version as the "production" version.

Adding and Modifying APKs

  1. Upload one or more APKs by calling the Edits.apks: upload method.

    This method uploads the APK into a storage "bucket", where it can be assigned to a "track" to deploy it to users. (If the edit is deleted or discarded, any APKs uploaded to that edit are also lost.)

  2. Release APKs on "tracks" by calling Edits.tracks: update. You can release APKs on the following tracks:

    • Testing tracks such as "alpha" and "beta"

      Alpha and beta versions of the app are deployed to the users you assign to the alpha and beta test groups. You assign users to these groups using the Google Play Console.

    • The internal testing track: "qa"

      Internal versions of your app are deployed to your internal test track as configured in the Google Play Console.

    • The production track: "production"

      Releases on the "production" track are deployed to all users. You can make use of staged releases on "production" track to safely deploy your release first to a small percentage of production users and then gradually increase this percentage as your confidence in the release grows.

    Simple-mode users should not put more than one APK to any track. Advanced-mode users using the multiple APK support can upload zero, one, or more APKs to each track.

Track name for form factor tracks

The track name for a form factor track is prefixed with a specific identifier.

Form Factor Prefix
Android Automotive OS automotive
Wear OS wear
Android TV tv

How to compute track name for a given form factor track?

Common track types like production, open testing and internal testing track have a well known track name.

Track Type Default Track Name
Production production
Open Testing beta
Internal Testing qa

The track name for a given form factor track can be computed as: "[prefix]:defaultTrackName". For example Wear OS form factor will have tracks with name: "wear:production", "wear:beta" and "wear:qa".

Closed testing tracks are created manually and they have custom names. So a closed testing track for a form factor with name $name will have track name of "[prefix]:$name".

APK Workflow Example

This section describes a typical way the Tracks API would be used. In this case, we assume you want to upload new versions of the APK for each track, and assign a number of users to receive a staged rollout version. (In practice, a developer would be unlikely to take all of these actions in the same operation; instead, you might update the beta version one day, create a staged release on "production" another day, and so on.)

  1. Open a new edit, as described in Edits Workflow
  2. Call the Edits.apks: upload method for each APK you want to upload. Pass the APK in the method's request body. (This places the APK in a storage area, but does not release it on a track or deploy it.) The method returns a version code for each APK you upload; you will use this version code to refer to the APK when you release it on a track.
  3. Call the Edits.tracks: update method for each track that you want to release APKs on. In the request body, pass a Edits.tracks resource containing the release you wish to rollout. For example, to release an APK with version code 88:

    {
    "releases": [{
      "versionCodes": ["88"],
      "status": "completed"
    }]
    }
    

    At this point, the APKs are still not available to users. As with other edits, the changes do not go live until you commit them.

  4. Call the Edits: commit method to commit the changes. After you do this, users on each track will be given the updated version of the APK. (As with all edits, it can take several hours for the changes to take effect.)

Staged Rollouts

When you have a new version of your APK that you want to gradually deploy, you may choose to release it as a "staged rollout" version. If you do this, Google Play automatically deploys it to the desired fraction of the app's users which you specify. If the "rollout" APK doesn't have any issues (such as crashes, etc.), you might increase the fraction of users who receive that version; when you are ready, you can deploy that APK as the new production version.

This section describes the steps you would go through to perform a staged rollout of an APK, then promote it to production:

  1. Create an edit, as described in Edits Workflow.

  2. Upload a new APK to the edit, using the Edits.apks: upload method.

  3. Start a "inProgress" staged release on the production track using the Edits.tracks: update method. Choose the fraction of users who should receive the new APK. At this point, the APK is still not available to any end users.

    {
    "releases": [{
      "versionCodes": ["99"],
      "userFraction": 0.05,
      "status": "inProgress"
    }]
    }
    

  4. Commit the changes in the active edit by calling Edits: commit. Over the next few hours, the new APK will be rolled out to users. The fraction of users you select will receive the new APK.

Depending on the success of the staged rollout you may then wish to increase the percentage of users eligible for that release or halt the release.

Increasing the user fraction for a staged rollout

Assuming you have an ongoing staged rollout at 5%, as described in the previous section, this section describes how to increase the percentage in the case where the release is going well:

  1. Create an edit, as described in Edits Workflow.

  2. Change the "inProgress" staged release on the production track using the Edits.tracks: update method. Increase fraction of users who should receive the new APK:

    {
    "releases": [{
      "versionCodes": ["99"],
      "userFraction": 0.1,
      "status": "inProgress"
    }]
    }
    

  3. Commit the changes in the active edit by calling Edits: commit. Over the next few hours, the new APK will be rolled out to users. The fraction of users you select will receive the new APK.

Halting a staged rollout

Assuming you have an ongoing staged rollout at 5%, as described in the previous section, this section describes how to halt the staged rollout in the case where you discover a problem:

  1. Create an edit, as described in Edits Workflow.

  2. Change the "inProgress" staged release on the production track using the Edits.tracks: update method. Set the status to "halted".

    {
    "releases": [{
      "versionCodes": ["99"],
      "status": "halted"
    }]
    }
    

  3. Commit the changes in the active edit by calling Edits: commit. Your release will no longer be available to new users.

If you later decide to resume a halted release you can do so by setting its status back to "inProgress".

Completing a staged rollout

Once you are happy with your staged rollout and wish to rollout the release to 100% of users you can set the release status to "completed":

  1. Create an edit, as described in Edits Workflow.

  2. Change the "inProgress" staged release on the production track using the Edits.tracks: update method. Set the status to "halted".

    {
    "releases": [{
      "versionCodes": ["99"],
      "status": "completed"
    }]
    }
    

  3. Commit the changes in the active edit by calling Edits: commit. Over the next few hours, the new APK will be rolled out to users. The fraction of users you select will receive the new APK.

Draft releases

Draft releases allow you to automatically upload APKs and create a release via the API which can later be deployed via the Google Play Console. To create a draft release on a track:

  1. Open a new edit, as described in Edits Workflow
  2. Call the Edits.apks: upload method for each APK you want to upload. Pass the APK in the method's request body. The method returns a version code for each APK you upload; you will use this version code to refer to the APK when you assign it to a release.
  3. Call the Edits.tracks: update method for each track that you want to release on. In the request body, pass a Edits.tracks resource containing the draft release you wish to create. For example:

    {
    "releases": [{
      "name": "My draft release",
      "versionCodes": ["88"],
      "status": "draft"
    }]
    }
    

  4. Call the Edits: commit method to commit the changes. Your draft release can now be inspected and rolled out via the Google Play Console or the API.

Specifying release notes

When releasing a new version of your application you can highlight what's new to users by specifying release notes on your release.

To do this use the "releaseNotes" field when supplying a Edits.tracks resource to the Edits.tracks: update method.

{
  "releases": [{
      "name": "Release with notes",
      "versionCodes": ["88"],
      "status": "completed",
      "releaseNotes": [
        {"language": "en-US", "text": "Describe what's new in this release."}
      ]
  }]
}