- Prerequisites
- Project configurations
- Apple developer portal configurations
- App Store Connect configurations
- Generate an App-specific password
- Create an Apple certificate repository
-
Configure your
hello-world-unity-mobile
project - Trigger the iOS build and deploy flows
- View flow status and output
Build and deploy a Unity project to TestFlight
This tutorial shows you how to configure a WVS Unity project so that you can use flows to build and deploy Unity applications to TestFlight. This tutorial uses the hello-world-unity-mobile
project as an example.
Prerequisites
To perform this tutorial, you must have the following:
- iOS 2022.1.1f1 support installed in Unity Editor.
- Subscription to the Apple Developer program.
- TestFlight installed on an Apple device.
Project configurations
To build and deploy applications to Testflight, you must configure several variables in your project. Each variable is a key-value pair.
The following table lists the variables that you need to configure and provides a description of their values.
Key | Value |
---|---|
WVS_APPLE_APP_NAME
| The exact name of your app in App Store Connect. |
WVS_APPLE_BUNDLE_IDENTIFIER
| The bundle ID of your app in App Store Connect. |
WVSUSR_APPLE_APPLICATION_SPECIFIC_PASSWORD
| The App-specific password for your app. |
WVSUSR_APPLE_CODE_SIGNING_GIT_ENCRYPTION_PASSWORD
| Use any secure password of your choice. |
WVSUSR_APPLE_CODE_SIGNING_GIT_PRIVATE_KEY
| Private SSH key. |
WVSUSR_APPLE_CODE_SIGNING_GIT_URL
| SSH Git URL of the project that contains the public SSH key. |
WVSUSR_APPLE_CONNECT_API_KEY
| App Store Connect API key. |
WVSUSR_APPLE_CONNECT_API_KEY_ID
| Key ID of the App Store Connect API key. |
WVSUSR_APPLE_CONNECT_API_KEY_ISSUER
| Issuer ID that issued the App Store Connect API key. |
WVSUSR_APPLE_DEVELOPER_PORTAL_TEAM_ID
| Team ID in App Store Connect. |
WVSUSR_APPLE_STORE_CONNECT_TEAM_ID
| Content provider ID. |
WVSUSR_UNITY_PASS
| Unity login password. |
WVSUSR_UNITY_USER
| Unity login email. |
The value of each key is either something that you need to configure or generate. The following sections show you how to configure or generate these values. We recommend that you copy each key-value pair to a text editor or spreadsheet as you complete the steps so that you can have an easy reference when configuring the variables in your project.
Apple developer portal configurations
Perform the steps in this section on the Apple developer portal. You can log in to the developer portal at developer.apple.com. You must have a subscription to the Apple Developer program.
Create a Bundle ID for your application
You need to create a bundle ID on Apple’s developer site before you can create your application in App Store Connect.
To create a bundle ID, perform the following steps:
- Go to the Certificates, Identifiers & Profiles page.
- In the navigation pane, click Identifiers.
- Click the + icon next to Identifiers.
- Under Register a new identifier, select App IDs.
- Click Continue.
- Under Select a type, select App.
- Under Register an App ID, configure as follows:
- Description: Enter a description of your App ID.
-
Bundle ID: Select Explicit and enter a bundle ID in the text field. We recommend that you use reverse DNS notation, for example,
com.example.MyProduct
.
- Click Continue.
-
Confirm that your information is correct and click Register.
Your application appears under the list of identifiers.
-
Copy and save the bundle ID for later reference.
The bundle ID that you configure is the value for the variable
WVS_APPLE_BUNDLE_IDENTIFIER
.
Get your Apple developer team ID
- Go to the Account page.
- Click the Membership details icon.
-
Copy and save the value for Team ID for later reference.
The Team ID is the value for the variable
WVSUSR_APPLE_DEVELOPER_PORTAL_TEAM_ID
.
App Store Connect configurations
Perform the steps in the section on App Store Connect. You can sign into App Store Connect at appstoreconnect.apple.com.
Create your application
- Go to the Apps dashboard.
- Click the + icon next to Apps.
- Select New app.
- In the New app popup window, configure your application as follows:
- Platforms: Select iOS.
- Name: Enter a unique name for your application.
- Bundle ID: Select the bundle ID that you created in the previous step.
-
SKU: Enter a unique SKU for your application. Example:
companyName.project.Name
. The SKU is not visible to users. - User access: Select Limited access.
-
Click Create.
Your application is created in App Store Connect.
Generate an App Store Connect API key
- Go to the Users and Access page.
- Click the Key tab.
- Click the + icon next to Active.
- Enter a name for the key. The name is for your reference only.
- Under Access, select the role for the key.
-
Click Generate.
The new key appears in the key list with a download option.
-
Download the key.
The content of the downloaded key file is the value for the variable
WVSUSR_APPLE_CONNECT_API_KEY
. -
On the Keys tab, you can find two other variable values:
-
Key ID for the key that you just generated is the value for the variable
WVSUSR_APPLE_CONNECT_API_KEY_ID
. -
Issuer ID is the value for the variable
WVSUSR_APPLE_CONNECT_API_KEY_ISSUER
.
-
Key ID for the key that you just generated is the value for the variable
Get your App Store Connect team ID
A Team ID is required to setup your project. The variable we’re referencing here is WVSUSR_APPLE_STORE_CONNECT_TEAM_ID
.
-
First go back to App Store Connect and confirm you are logged in. If you are not logged in, the next step will not work right.
-
Go to appstoreconnect.apple.com/WebObjects/iTunesConnect.woa/ra/user/detail and you will need to grab some values from this page.
You get a JSON response displayed on the page.
-
Find the
associatedAccounts
array.Your teams are listed in this array as
contentProvider
objects. - Find the
contentProvider
associated with the team that you want to use. -
Copy and save the value for
contentProviderID
for later reference.The
contentProviderID
is the value for the variableWVSUSR_APPLE_STORE_CONNECT_TEAM_ID
.
Generate an App-specific password
- Sign in to Apple using your developer account credentials.
- Under Sign-in and security, select App-specific passwords.
- In the popup window, enter a unique name associated with your application.
- Click Create.
- Enter your Apple account password.
- Click Continue.
-
Copy and save the generated password for later steps.
The generated password is the value for the variable
WVSUSR_APPLE_APPLICATION_SPECIFIC_PASSWORD
. - Click Done.
Create an Apple certificate repository
The certificate repository is where your signing certificates from Apple are stored.
Generate an SSH key
Run the following command in Git Bash (Windows) or Terminal (macOS):
ssh-keygen -q -t rsa -N '' -f temp_rsa <<<y >/dev/null 2>&1
This creates temp_rsa
which stores the private key and temp_rsa.pub
which stores the public key.
The contents of temp_rsa
is the value of the variable WVSUSR_APPLE_CODE_SIGNING_GIT_PRIVATE_KEY
.
Create a project to store Apple’s signing certificates
- Create an empty WVS project:
- Go to the project creation page.
- Click Create from template.
- Next to Empty, click Use Template.
- Configure the project as follows:
- Project name: Enter a unique name for the project.
- Project URL: Select your user name.
- Visibility level: Select Private.
-
Click Create.
You are taken to the project’s homepage.
- In the project’s homepage, click Clone.
-
Under Clone with SSH, copy and save the SSH URL for later reference.
The SSH URL for the project is the value for the variable
WVSUSR_APPLE_CODE_SIGNING_GIT_URL
. - In the navigation pane, click Project settings > Version control.
- Next to Deploy Keys, click Expand.
- Enter a title for your key.
- Copy the contents of
temp_rsa.pub
into the Key text field. - Select the checkbox to grant write permission to this key.
- Click Add key.
Configure your hello-world-unity-mobile
project
Fork and clone the hello-world-unity-mobile
project. For this tutorial, name the forked project hello-world-unity-mobile-tutorial
. Once the project is forked and cloned, perform the following tasks:
- Configure project variables
- Configure the bundle ID in Unity Editor
- Connect the build and deploy flows.
Configure project variables
- Open your
hello-world-unity-mobile-tutorial
project in the WVS Web Client. - In the navigation pane, click Project settings > CI/CD.
- Next to Variables, click Expand.
- Click Add variable and add all of the following variables and their values one by one:
WVS_APPLE_APP_NAME
WVS_APPLE_BUNDLE_IDENTIFIER
WVSUSR_APPLE_APPLICATION_SPECIFIC_PASSWORD
WVSUSR_APPLE_CODE_SIGNING_GIT_ENCRYPTION_PASSWORD
WVSUSR_APPLE_CODE_SIGNING_GIT_PRIVATE_KEY
WVSUSR_APPLE_CODE_SIGNING_GIT_URL
WVSUSR_APPLE_CONNECT_API_KEY
WVSUSR_APPLE_CONNECT_API_KEY_ID
WVSUSR_APPLE_CONNECT_API_KEY_ISSUER
WVSUSR_APPLE_DEVELOPER_PORTAL_TEAM_ID
WVSUSR_APPLE_STORE_CONNECT_TEAM_ID
-
WVSUSR_UNITY_PASS
(The password of your Unity account.) -
WVSUSR_UNITY_USER
(The email of your Unity account.)
Configure the bundle ID in Unity Editor
- Open
hello-world-unity-mobile-tutorial
in Unity Editor. - Click Edit > Project Settings > Player.
- Select the iOS tab.
- Expand Other Settings.
- Under Identification, configure the value for Bundle Identifier to match the bundle ID that you configured for your application earlier.
Add Flows to your project
If you’re setting up your own project, you will need to add the correct flows to get the project to build properly. If you’re using an example project, you can skip this step since flows are already included in the project.
We will use the WVS Command-Line tool to set this up. Keep in mind, while running any of these commands, if you would like additional information on any command, you can always append ` –help` at the end.
Learn more about the CLI tool in the Documentation for the CLI.
-
Open up your command-prompt and navigate to your project directory.
cd c:\wvsProjects\my-cool-test-project
-
Run the following to begin a changelist. You can add any name to your changelist in place of the example.
wvs changelist begin --name "Adding a flow"
-
To see a list of available flows, run the following in your command prompt:
wvs flow registry
-
The flows we will want to add are the following:
Flow Name Description build_unity_ios iOS Build for Unity deploy_testflight_ios iOS deployment to TestFlight Both flows are required to be able to successfully deploy. The first flow (build_unity_ios) builds an
.ipa
which is the
required build format that will work on iOS devices. The second flow (deploy_testflight_ios) will take the.ipa
and help you deploy to your device. -
To add, run the following two commands (separately) in your command prompt:
wvs flow add build_unity_ios
Hit Enter, an
OK
should be returned.wvs flow add deploy_testflight_ios
Hit Enter - An
OK
should be returned. -
To check if they were added correctly, run:
wvs flow status
-
Your output should display the following:
Instance Name Registry Name Catgry Enabled build_unity_ios_1 build_unity_ios build true deploy_testflight_ios_1 deploy_testflight_ios deploy true The name of your flow is the Instance Name. If you need to make changes in the future, you would use the Instance Name of your flow.
Connect the build and deploy flows
- In a terminal window, navigate to the directory of your Unity project.
-
Run the following command to connect the flows:
wvs flow connect build_unity_ios_1 to deploy_testflight_ios_1
Example:
C:\wvsProjects\hello-world-unity-mobile-tutorial>wvs flow connect build_unity_ios_1 to deploy_testflight_ios_1 OK C:\wvsProjects\hello-world-unity-mobile-tutorial>_
-
Now submit your changes by running the following:
wvs changelist finish
Return to your project on the WVS web app. From the left-hand side, locate Outputs > Builds to view your build progress.
Trigger the iOS build and deploy flows
The iOS build and deploy to TestFlight flows are configured to run only when you add a trigger string to the commit message.
- Open the WVS Desktop Client.
- Click My projects.
- Select the
hello-world-unity-mobile-tutorial
project and click Switch project. - Click New Changelist.
- Enter a name for the changelist.
- Click Start changelist.
-
In the Changelist notes field, enter the following text:
-execute_ios
This is the trigger string to trigger the flows that create an iOS build and deploy it to TestFlight.
- Click Commit changelist.
- Click Push changelist.
View flow status and output
View flow status
When the flow is building, you can view the status of the flow by performing the following steps:
- Go to the WVS Web Client and select the
hello-world-unity-mobile-tutorial
project. - In the navigation panel, click Flows > Pipelines.
- Click the pipeline ID number to view the status of the flows in the pipeline.
View flow outputs
When the pipeline finishes running, you can view the build outputs in the WVS Web Client by navigating to Outputs > Builds.
View TestFlight deployment
- Go to your AppStore Connect Account and select your App.
-
Select the TestFlight tab.
Your build should be displayed listed under Build. You can now add users to your project.
Troubleshooting
For additional support, please reach out to us on our Discord.
Was this helpful?
We would love to hear your feedback, Submit a ticket in our Issue Tracker.