Setting up Continuous Delivery Pipelines for platforms wasn’t a straightforward task, it was more challenging when it comes to scripting the pipelines in the code. It might be because of native Apple developer tools like xcodebuild, agvtool, security, transporter, altool etc wasn’t easy to understand to form pipelines as a code. Another big challenge was Apple never provided an API to connect to Apple Developer portal or iTunes Connect. That’s the reason most of the iOS Developer has chosen third-party tools like Fastlane and Nomad-CLI for automating iOS deployment pipelines. However, at WWDC 2018, Apple has finally announced API to talk to both Apple Developer portal and iTunes Connect. Apple has also combined Apple Developer Portal and iTunes Connect and rebranded it as ‘App Store Connect”. You should definitely watch the WWDC sessions on What’s New in App Store Connect and Automating App Store Connect
Whats New in App Store Connect
On top of App Store Connect API, there are few more great features launched this year, we will see this one by one.
Transporter on Linux
Apple command line tools transporter was being used for uploading apps to App Store. Now, this tool has been supported on Linux which will help us to use Linux servers to upload IPA files to App Store. The transporter tool will use same API token generated for the session to connect to App Store Connect.
TestFlight Public Links
Apple has launched TestFlight public links support where we can share the link and get peoples to test out the beta app. Public links can be sent out to up to the 10K testers but we can set the limit. The links can be disabled or enabled anytime to control the numbers testers. The most of the TestFlight features like creating groups, assigning builds to the group, manage public links, manage testers and test information can be automated using an App Store Connect API.
Sales and Trends
App Store Connect will have Sales and Trends section which shows all the information about the revenue, analytics and territories data so that we can get all the information in one place.
App Store Connect iOS App
Apple also launched “App Store Connect” iOS app so that we can perform almost all the activities from the iOS devices without the need to go to the website. In the iOS app, we can
- See the Trends, Sales, and Updates, In-App Purchases, App Bundles
- All our Apps and ability to switch to the development team.
- Detailed App Information, release/reject apps, manage user reviews and set up notification
There are many things about pre-orders, In-App-Purchases but we are not going to cover as part of this post. Now let’s dive into the App Store Connect API and how we can use those API for automating our release pipelines.
Use of App Store Connect API
App Store Connect API is standard RESTful API based on JWT (JSON Web Tokens) for authentication and can be accessed from all platforms. With App Store Connect API, we can automate almost everything related to App Store including
- Managing certificates, provisioning profiles, managing device ID and bundle ID
- Managing users, roles and App access of App Store Connect
- Managing TestFlight and Beta Testers and Public Links
- Downloading financial reports and Sales reports
The App Store Connect API has base URL api.appstoreconnect.apple.com and from that base, we can make requests to various endpoints. The API also has version numbers so that if Apple changes the versions of API then we can still use old endpoints without breaking our code.
Authorizing App Store Connect API
Before jumping into the App Store Connect API, you have to perform the big task of generating token those can be used to access API. Without a token, you won’t be able to get the response from App Store Connect API. As we know that App Store Connect has very sensitive information the API has to be very secure also we want to make sure that we have to access only our Apps, not of others. Apple used JWT also known as JSON Web Token standard to make a secure connection between App Store Connect and your machine. In order to get access to the token, we have to create a private key from App Store connect to the web interface.
Generate API Key
In order to generate API key, we have to log in to App Store Connect web interface and click on API Key tab to create New API key. We can create API key for a specific purpose or admin API key which can access all the App Store Connect API.
Download Private Key
Once API key is generated we will get an ISSUER_ID and option to download API key or Private Key. There are a couple of things which are important to keep in mind whilst dealing with the private key.
- The private key can be downloaded only once from App Store Connect. We have to make sure we have to keep it secure once downloaded.
- The private key never expires and used to work as long as it’s valid even it’s compromised so if you think that your private key is compromised, revoke it from App Store Connect as soon as possible.
The private key usually in the .p8 format
Generate JWT Token
As mentioned earlier, JWT is used to generate the token that has been used by App Store Connect API. The process of generating token requires following six details
- Issuer ID: The ID found on the top of App Store Connect
- Private Key ID: The ID associated with Private Key on App Store Connect
- Expiration Time: 20 min maximum, the token cannot be valid more than 20 min so that we have to make sure that, we will create new token before it expires.
- Audience: This is constant with API version value usually “applestoreconnect-v1”
- Algorithm: This is JWT algorithm required to generate token e.g ES256
Once we have all these details, we will be able to generate JWT token using your preferred scripting language. The JWT is almost available in all languages including Swift but it would be quicker to generate it using dynamic or interpreted languages like Ruby or Python. Here is a Ruby script that has been used in WWDC demo.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
require "base64" require "jwt" ISSUER_ID = "YOUR_ISSUER_ID" KEY_ID = "YOUR PRIVATE KEY ID" private_key = OpenSSL::PKey.read(File.read(path_to_your_private_key/AuthKey_#{KEY_ID}.p8)) token = JWT.encode( { iss: ISSUER_ID, exp: Time.now.to_i + 20 * 60, aud: "appstoreconnect-v1" }, private_key, "ES256", header_fields={ kid: KEY_ID } ) puts token |
We can save this file as jtw.rb somewhere. You need to have JWT ruby gem installed for this script to run properly. Just replace the value of ISSUER_ID and KEY_ID and you will be good to go. This script can be run using
|
1 |
$ ruby jwt.rb |
This will return a long token that we can use to access an App Store Connect API, we also need to create another token if we want to continue using API after 20 minutes.
Use Token
Now that, we have seen how to generate a token to access an App Store Connect API, we can use it by passing authorization header. e.g to get a list of all user we can use
|
1 |
$ curl https://api.appstoreconnect.apple.com/v1/users --Header "Authorization: Bearer lOOOOOOOOOOOONG_GENERATED_TOKEN" |
This will list all the uses of App Store Connect. Remember that we have to use this token with every request we make and we have to create new token after every 20 minutes.
Using AppStore Connect API
Getting User Data
If we want to get a list of all the users we can make GET request to users endpoint like this
|
1 |
GET api.appstoreconnect.apple.com/v1/users |
This will return all the users in the App Store connect but we can drill down information of the particular user using the user ID. To get the information about the one user we can pass the ID to the request
|
1 |
GET api.appstoreconnect.apple.com/v1/users/XYZ123455 |
Inviting a User
Creating a user on App Store Connect required the user to be invited by email. The user then accepts the invitation and join the Apple developer team. We can invite the user using App Store Connect API like this
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
$ > POST /v1/userInvitations { "data": { "type": "userInvitations", "attributes": { "firstname": "Shashi", "lastname": "Jagtap", "email": "shashikant.jagtap@opple.com", "role": [ADMIN], "allAppsVisible": true } } } |
Note that we have the type of userInvitations in the request so that we will get the new users created on App Store Connect of all goes well. Similarly, we can change, delete users using the same API.
Managing Groups and Testers
This is a bit tricky as one tester can be part of many groups and we have to make sure that relationship between the testers and groups is maintained. App Store Connect API has solved this using the concept of relationships, we can get all the groups using GET v1/betaGroups and get an ID of a group. It will also list all the tester information associated with groups. We can also get the list of all the groups and beta testers including their information using the
|
1 |
> GET /v1/betaGroups?include=betaTesters |
We can add tester to the particular group using making a simple post request
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
> POST /v1/betaGroups/GROUP_ID/relationships/betaTesters { "data": [ { "type": "betTester", "id": "TESTER_ID" {, { "type": "betTester", "id": "TESTER_ID2" } ] } |
This will add those two testers to the beta groups. Similarly, we can remove the testers from the beta group by simply making the DELETE request. Now that, we have seen basic of API and will stop here as there are many combinations how we can use this API for a different purpose.
Things to Remember
As of now, we have seen that how to generate tokens and access the App Store Connect API, now we will see some of the best practices shared during WWDC to make this workflow more useful
- As the Private key is very important, we have to secure it.
- The authorization token is only valid for 20 min so we can add automated scripted strategy to renew the token after 18 minutes so that we can reuse the existing token to save time as well as there isn’t any risk to fail ou request.
- App Store Connect API returns lots of links and we should make use those links
- The API will be documented at URL https://developer.app.com/wwdc18/303 as soon as its published.
Conclusion
App Store Connect API has opened the possibility of automating entire App Store Connect. This will allow developers to write tools on top of App Store Connect API and use them efficiently. No wonder, there will be various new tools start to appear on GitHub to automate releases and CI/CD pipelines. Also, there will be huge refactor required for existing tools like Fastlane. What you think of new App Store Connect API, Waive in the comments below.