Introduction
You can easily create builds for Apps in our system. This article will walk the reader through that process.
For a handy utility that handles this for you, please see our build_47 project on Github. build_47 is a simple command line tool that allows you to easily post builds (iOS .ipa's or Android .apk's) to App47 for distribution. Even if you don't plan on using this library, looking at the code will undoubtably help in understanding our API.
Note: You must have already created the App before you can associate a build to it. Accordingly, all RESTful URLs have App IDs in them.
Creating App Builds
API Details
There are a number of required attributes:
-
platform
-
needs to be “iOS” or “Android” (see note about
environment
)
-
-
environment
-
can be either:
-
“Production”
-
“Test”
-
Note: If you send a test build and your platform is Android then you can include a list of test user ids. See note† below about alternate attributes.
-
-
-
-
file_url
-
this needs to be a URL to the build file – http or https is supported
-
Please see note† below regarding providing an alternate attribute dubbed
upload
that is your build file – that is, you can essentially push a binary file via this API
-
-
build_file
-
this is simply the name of the file; for example, myapp.ipa
-
-
release_notes
You can optionally provide an active
parameter – set it to true or fase. By default, if this parameter isn't present, it is set to false. You can also pass in a notify
parameter, which allows you to specify a list of email addresses. Upon successful processing of the uploaded build, these email addresses will receive an email notification of the event. This parameter is simply an array of valid email addresses.
Note†: You can provide a file to upload as a part of a POST (i.e. Build creation); that is, you don't have to provide the attribute file_url
but instead, provide an attribute dubbed upload
. What's more, you must make sure the corresponding POST is multipart (many libraries handle this for you). See the 2nd example below for this in action.
You may specify JSON or XML as an exchange format. XML is default; thus, if you'd like to use JSON, please use HTTP headers Accept
and Content-Type
.
URLs:
Action | HTTP method | URL |
---|---|---|
create | POST | https://cirrus.app47.com/api/apps/:app_id/builds |
read | GET | https://cirrus.app47.com/api/apps/:app_id/builds/:build_id |
update | PUT | https://cirrus.app47.com/api/apps/:app_id/builds/:build_id |
delete | DELETE | https://cirrus.app47.com/api/apps/:app_id/builds/:build_id |
Creating Builds for Apps
As an example of creating an App, here is a Node.js call (written in CoffeeScript) using a RESTful POST:
options = { headers: {'X-Token':'ZSUVSOtxOdqpzJ9u24CPIg', 'Accept':"application/json", 'Content-Type': 'application/json' } } opt_file_url = "https://s3.amazonaws.com/App-Builds/Demonstration/Milton/1319040398.ipa" addBuildForApp = (appId) -> console.log "adding build to app " + appId buildOpts = options buildOpts['data'] = JSON.stringify({ build :{ platform: "iOS", environment: "Production", file_url: opt_file_url, build_file: "1319040398.ipa", release_notes: "blah" }}) client.post("http://0.0.0.0:3000/api/apps/" + appId + "/builds", buildOpts).on('2XX', (data, response) -> console.log JSON.parse(JSON.stringify(data)))
Curl Example
Using curl—which can be found or installed on almost any machine—the following examples will upload your build file assuming the name of the file is either @build.ipa or @build.apk.
If your file name is different, then simply update the command:
curl -v -H "X-Token: ZSUVSOtxOdqpzJ9u24CPIg" -H "Accept: application/json" -X POST https://cirrus.app47.com/api/apps/537276cb80993a002b005b69/builds -F "build[platform]=Android" -F "build[environment]=Test" -F "build[build_upload]=@build.apk" -F "build[release_notes]=This is the uploaidng of a new build file" -F "build[make_active]=true"
or upload an android build in the production environment
curl -v -H "X-Token: ZSUVSOtxOdqpzJ9u24CPIg" -H "Accept: application/json" -X POST https://cirrus.app47.com/api/apps/537276cb80993a002b005b69/builds -F "build[platform]=Android" -F "build[environment]=Production" -F "build[build_upload]=@build.apk" -F "build[release_notes]=This is the uploaidng of a new build file" -F "build[make_active]=true"
or upload an iOS build, marking it to become active after evaluation
curl -v -H "X-Token: ZSUVSOtxOdqpzJ9u24CPIg" -H "Accept: application/json" -X POST https://cirrus.app47.com/api/apps/537276cb80993a002b005b69/builds -F "build[build_upload]=@build.ipa" -F "build[release_notes]=This is the uploaidng of a new build file" -F "build[make_active]=true"
or upload both the .ipa file and dsym.zip file at the same time
curl -v -H "X-Token: ZSUVSOtxOdqpzJ9u24CPIg" -H "Accept: application/json" -X POST https://cirrus.app47.com/api/apps/537276cb80993a002b005b69/builds -F "build[build_upload]=@build.ipa" -F "build[release_notes]=This is the uploaidng of a new build file" -F "build[make_active]=true" -F "build[dsym_file]=@dsym.zip"
A couple of things to note:
-
Remember when uploading test builds for Android you need to also specify your test users, theses are generally a subset of your user base that has access to the app. If you click on Edit on the My Apps page and then navigate to the Users tab, you'll see a Users field and a Test Users field. Users can only download production builds, while test users can download both. This is for Android and Windows builds only; we can figure this out on iOS.
-
The default for “build[make_active]” is false, so if you want to manually activate builds, then leave that parameter off.
Associating test users to a build
As mentioned above, if your build is an Android one, you can associate specific users to a test build. That is, you can provide a list of ids as a part of your request (JSON or XML). For example, the following code (in Ruby) creates a JSON document for a new Android build and associates two users as test users:
android_build_doc = { :build => { :platform => "Android", :environment => "Test", :upload => File.new("./etc/ConfigActivity-debug.apk"), :build_file => "ConfigActivity-debug.apk", :release_notes => "Release notes for Test application" }, :app => { :test_user_ids => ["4f01e86a8092730001000016", "4f22b7b9df1020000100000a"] } }
Next, a request can be created (using Ruby again) that does two things:
-
Uploads a binary file (in this case, an APK)
-
Associates two users (via 'test_users_ids' in the 'app' attribute)
RestClient.post app_url + "/api/apps/#{app_id}/builds", android_build_doc, {"X-Token"=> acct_token, :accept => :json}
Troubleshooting
Having some challenges getting a JSON document along with a file posted? If you haven't already done so, please have a look at our build_47 utility. This handy command line client can get you started.
HTTP POST Low-Level Details
Your POST should be formatted as follows:
POST /api/apps/some_app_id/builds HTTP/1.1 Host: cirrus.app47.com Content-Length: 611 Content-Type: multipart/form-data; boundary=265141 Accept: application/json Accept-Encoding: gzip, deflate X-Token: <apikey> --265141 Content-Disposition: form-data; name="build[upload]"; filename="sample.ipa" Content-Type: text/plain <binary data> --265141 Content-Disposition: form-data; name="build[build_file]" sample.ipa --265141 Content-Disposition: form-data; name="build[release_notes]" Release notes for Test application --265141 Content-Disposition: form-data; name="build[platform]" iOS --265141 Content-Disposition: form-data; name="build[environment]" Production --265141--
Comments
0 comments
Please sign in to leave a comment.