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:

  1. Go to the Certificates, Identifiers & Profiles page.
  2. In the navigation pane, click Identifiers.
  3. Click the + icon next to Identifiers.
  4. Under Register a new identifier, select App IDs.
  5. Click Continue.
  6. Under Select a type, select App.
  7. 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.
  8. Click Continue.

  9. Confirm that your information is correct and click Register.

    Your application appears under the list of identifiers.

  10. 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

  1. Go to the Account page.
  2. Click the Membership details icon.

  3. 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

  1. Go to the Apps dashboard.
  2. Click the + icon next to Apps.
  3. Select New app.
  4. 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.

  5. Click Create.

    Your application is created in App Store Connect.

Generate an App Store Connect API key

  1. Go to the Users and Access page.
  2. Click the Key tab.
  3. Click the + icon next to Active.
  4. Enter a name for the key. The name is for your reference only.
  5. Under Access, select the role for the key.

  6. Click Generate.

    The new key appears in the key list with a download option.

  7. Download the key.

    The content of the downloaded key file is the value for the variable WVSUSR_APPLE_CONNECT_API_KEY.

  8. 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.

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.

  1. 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.

  2. 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.

  3. Find the associatedAccounts array.

    Your teams are listed in this array as contentProvider objects.

  4. Find the contentProvider associated with the team that you want to use.

  5. Copy and save the value for contentProviderID for later reference.

    The contentProviderID is the value for the variable WVSUSR_APPLE_STORE_CONNECT_TEAM_ID.

Generate an App-specific password

  1. Sign in to Apple using your developer account credentials.
  2. Under Sign-in and security, select App-specific passwords.
  3. In the popup window, enter a unique name associated with your application.
  4. Click Create.
  5. Enter your Apple account password.
  6. Click Continue.

  7. Copy and save the generated password for later steps.

    The generated password is the value for the variable WVSUSR_APPLE_APPLICATION_SPECIFIC_PASSWORD.

  8. 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

  1. Create an empty WVS project:
    1. Go to the project creation page.
    2. Click Create from template.
    3. Next to Empty, click Use Template.
    4. Configure the project as follows:
      • Project name: Enter a unique name for the project.
      • Project URL: Select your user name.
      • Visibility level: Select Private.

    5. Click Create.

      You are taken to the project’s homepage.

  2. In the project’s homepage, click Clone.

  3. 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.

  4. In the navigation pane, click Project settings > Version control.
  5. Next to Deploy Keys, click Expand.
  6. Enter a title for your key.
  7. Copy the contents of temp_rsa.pub into the Key text field.
  8. Select the checkbox to grant write permission to this key.
  9. 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

  1. Open your hello-world-unity-mobile-tutorial project in the WVS Web Client.
  2. In the navigation pane, click Project settings > CI/CD.
  3. Next to Variables, click Expand.
  4. 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

  1. Open hello-world-unity-mobile-tutorial in Unity Editor.
  2. Click Edit > Project Settings > Player.
  3. Select the iOS tab.
  4. Expand Other Settings.
  5. 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.

  1. Open up your command-prompt and navigate to your project directory. 

      cd c:\wvsProjects\my-cool-test-project

  2. 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"

  3. To see a list of available flows, run the following in your command prompt: 

      wvs flow registry

  4. 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.

  5. 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.

  6. To check if they were added correctly, run: 

      wvs flow status

  7. 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

  1. In a terminal window, navigate to the directory of your Unity project.

  2. 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>_

  3. 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

note
You can skip this step if you are working in your own project. This step is setup for users testing out the Community projects.


The iOS build and deploy to TestFlight flows are configured to run only when you add a trigger string to the commit message.

  1. Open the WVS Desktop Client.
  2. Click My projects.
  3. Select the hello-world-unity-mobile-tutorial project and click Switch project.
  4. Click New Changelist.
  5. Enter a name for the changelist.
  6. Click Start changelist.

  7. 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.

  8. Click Commit changelist.
  9. 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:

  1. Go to the WVS Web Client and select the hello-world-unity-mobile-tutorial project.
  2. In the navigation panel, click Flows > Pipelines.
  3. 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

  1. Go to your AppStore Connect Account and select your App.

  2. 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.


Report a problem with this page.