APKs and Tracks

The Google Play Developer API allows you to upload new APKs for your apps and assign 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. Assign APKs to "tracks" by calling Edits.tracks: update. You can assign APKs to the following tracks:

    • "alpha"

    • "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 Developers Console.

    • "rollout"

      The "rollout" version (short for "staged rollout") is deployed to a limited percentage of your users. When you assign the APK to the "rollout" track, you also designate what percentage of users should receive that version (allowable percentages range from 5% to 50%); the specified percentage of users are selected at random. Typically, you gradually increase the rollout percentage until you are ready to fully deploy that version of the app.

    • "production"

      The "production" version is deployed to all remaining users; that is, to all users who are not on the alpha or beta test list, and who have not been randomly assigned to receive a rollout version.

    Simple-mode users should not assign 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.

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, change the "rollout" version to "production" on 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 assign it to 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 assign it to a track.
  3. Call the Edits.tracks: update method for each track that you want to assign APKs to. In the request body, pass a Edits.tracks resource specifying the following:

    • "track": The release track that you're assigning APKs to.
    • "versionCodes": List of the version codes of the APKs that you're assigning to this track.
    • "userFraction": (Only specified if "track" is "rollout".) Portion of the users who should get the staged rollout version of the APK.

    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 a fraction of the app's users; you can choose that fraction, from a number of allowable values. 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. Assign the new APK to the "rollout" track, using the Edits.tracks: update method. Choose the fraction of users who should receive the new APK. (Acceptable values are 0.05, 0.1, 0.2, and 0.5, as described in Edits.tracks.) At this point, the APK is still not available to any end users.

  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.

  5. Depending on the success of the staged rollout, you might do any of the following:

    • If the APK is successful, you might increase the fraction of users who should get it. To do this, open a new edit and call Edits.tracks: patch, and set a higher rollout fraction. (As before, the maximum rollout fraction is 0.5.) Commit the changes, and the rollout app will be deployed to more users. For example, if APK version 123 had been deployed to 5% of the users and you wanted to increase the rollout to 10%, you would call Edits.tracks: patch and pass the following JSON object:
      {
        "userFraction": 0.1
      }
      
    • To replace the existing rollout APK version (or versions) with a new one, open a new edit, upload the new version of the APK (with Edits.apks: upload), and call Edits.tracks: update to assign the new APK to the "rollout" track (and remove the old APK from that track). Once you commit the edit, your users will be given an appropriate version of the app (with the requested fraction getting the new rollout version, and the rest getting your production version).

      For example, suppose you have version 88 as the "production" version, and version 99 as the "rollout" version, with a userFraction of 0.1 (10% of the users); and suppose you want to replace that rollout version with a new APK, version 105. Initially, 10% of your users would have version 99, and the remaining 90% would have version 88. Call Edits.tracks: update with the following JSON object:

      {
        "versionCodes": [105],
      }
      
      After the change takes effect, the 10% of users who had version 99 will receive version 105; the users who already had version 88 will not be affected.

    • To complete the rollout, open a new edit and call Edits.tracks: update twice: once to assign the current APK version to the "production" track, and once to pass an empty versionCodes list for the "rollout" track. When you commit the edit, the old rollout version will be deployed to all of your app's users.

      For example, suppose the current production version is 999, and the current rollout version is 1100. To promote the rollout version to production, call Edits.tracks: update. Call it once to assign version 1100 to the "production" track, passing this JSON object:

      {
        "track": "production",
        "versionCodes": [1100]
      }
      
      And call the method a second time to clear out the "rollout" track, passing this JSON object:
      {
        "track": "rollout",
        "versionCodes": []
      }
      
      (It doesn't matter what order you make the calls in, since both actions will take effect at once when you commit the edit.) After you commit the edit, the users who did not already have version 105 of the app will receive that version.