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

  1. Go to appstoreconnect.apple.com/WebObjects/iTunesConnect.woa/ra/user/detail.

    You get a JSON response displayed on the page.

  2. Find the associatedAccounts array.

    Your teams are listed in this array as contentProvider objects.

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

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

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

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.

  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.