---
title: Set Up Native Configurations
description: Set the app name and package name of iOS and Android builds in Capawesome Cloud with native configurations — no extra tooling or build scripts required.
---

# Set Up Native Configurations

A **native configuration** is a named, per-app record that Capawesome Cloud applies to your native project right before a build starts. Instead of committing a different app name or package name for every variant of your app, you keep one project and pick the native configuration you want at build time.

Every native configuration has a name and two optional fields:

| Field | Description |
| --- | --- |
| **Display name** | The app name that is displayed on the home screen. |
| **Package name** | The unique identifier of the app — the application ID on Android, the bundle ID on iOS. |

Both fields are optional. A field you leave empty is left untouched in the native project, so a native configuration can change just the name, just the identifier, or both.

This is the usual setup for white-label apps that ship the same code base under different brands, and for development, staging, and production variants that need to live side by side on the same device.

!!! note "Android and iOS only"

    Native configurations apply to native projects. A web build ignores the app's default native configuration, and selecting one explicitly is rejected.

## Create a native configuration

=== "CLI"

    Create a native configuration with the [`apps:configurations:create`](../cli/commands.md#appsconfigurationscreate) command:

    ```bash
    npx @capawesome/cli apps:configurations:create \
      --name staging \
      --display-name "My App (Staging)" \
      --package-name com.example.app.staging
    ```

    Use [`apps:configurations:list`](../cli/commands.md#appsconfigurationslist) and [`apps:configurations:get`](../cli/commands.md#appsconfigurationsget) to inspect what you have, [`apps:configurations:update`](../cli/commands.md#appsconfigurationsupdate) to change a value, and [`apps:configurations:delete`](../cli/commands.md#appsconfigurationsdelete) to remove one.

    Pass an empty string to clear a value again — with `--display-name ""`, the app name in your project is left untouched from then on.

=== "Console"

    Open the [Native configurations](https://console.cloud.capawesome.io/apps/_/configurations){:target="_blank"} page in the **Build** section of your app, click **Create native configuration**, and enter a name plus the values you want to apply.

Names are unique per app and compared case-insensitively, so `Staging` and `staging` are the same name.

## Use a native configuration in a build

=== "CLI"

    Pass `--configuration` to [`apps:builds:create`](../cli/commands.md#appsbuildscreate):

    ```bash
    npx @capawesome/cli apps:builds:create \
      --platform ios \
      --git-ref main \
      --type app-store \
      --configuration staging
    ```

=== "Console"

    In the **Build from Git** dialog, select the native configuration from the **Native configuration** dropdown before starting the build.

## Set a default native configuration

You can set a default native configuration that applies to every build that doesn't select one — useful when one identity is the normal case and the others are exceptions.

In the [Console](https://console.cloud.capawesome.io/){:target="_blank"}, open your app's **Settings**, and in the **Builds** section enable the **Default native configuration** toggle, select the native configuration, and save.

Capawesome Cloud resolves the native configuration for a build in this order:

1. The native configuration selected for the build.
2. The app's default native configuration.
3. None — the native project is built exactly as it is committed.

An [automation](../automations/index.md) can carry a native configuration of its own, which is used for every build it triggers. The app's default is **not** applied to automation-triggered builds, so an automation without a native configuration always builds the project as committed.

## How native configurations are applied

Native configurations are applied after the dependencies are installed and before the [web build script](web-build-script.md) runs and the platform is synced. Only the values you set are written — everything else in your project is left alone.

### Android

- `applicationId` in `app/build.gradle` (or `app/build.gradle.kts`)
- The string resources `app_name` and `title_activity_main` in `app/src/main/res/values/strings.xml`
- The string resources `package_name` and `custom_url_scheme` in the same file — but only while they still hold the previous application ID, so a deliberately customized URL scheme is preserved

!!! warning "Firebase and google-services.json"

    If your project uses `google-services.json`, it must contain a client entry for the new `applicationId` — otherwise the Google Services Gradle plugin fails the build with `No matching client found for package name`. Add an app with the new package name to your Firebase project and commit the regenerated file. A single `google-services.json` can hold the client entries of all your variants.

### iOS

- `PRODUCT_BUNDLE_IDENTIFIER` in `App.xcodeproj/project.pbxproj`
- `CFBundleDisplayName` in the `Info.plist` of the main app target

The bundle identifier is substituted as a prefix across all targets, so app extensions keep their suffix: with a main target moving from `com.example.app` to `com.example.staging`, `com.example.app.ShareExtension` becomes `com.example.staging.ShareExtension`.

!!! warning "Provisioning profiles must match the new bundle ID"

    A signed iOS build needs a provisioning profile for the **new** bundle identifier. If the profile you build with is still tied to the old one, the build fails during code signing. Register the new identifier in the Apple Developer portal, create a matching profile, and upload it to the [signing certificate](certificates/ios.md) you use for the build.

### Cordova

In a Cordova project, the values are written to `config.xml` instead of the platform projects:

- The `id` attribute of the `<widget>` element
- The `<name>` element

`cordova prepare` then propagates both values into the Android and iOS platform projects.

## Advanced: Trapeze

Native configurations cover the two settings that change most often. For everything else — version names, entitlements, or arbitrary edits to `Info.plist`, `build.gradle`, and `AndroidManifest.xml` — use [Trapeze](https://trapeze.dev/){:target="_blank"}, a mobile app configuration tool that you run yourself as part of the build.

Trapeze runs in your [web build script](web-build-script.md), which executes after the native configuration has been applied. If both change the same value, the Trapeze value wins.

### Installation

First, install Trapeze as a development dependency in your project:

```bash
npm install --save-dev @trapezedev/configure
```

### Configuration File

Create a configuration file named `capawesome.yml` in the root of your project. This file defines the native project settings you want to overwrite.

Here's a basic example that modifies the App ID and display name:

```yaml
platforms:
  android:
    packageName: com.example.myapp
    appName: My App
  ios:
    bundleId: com.example.myapp
    displayName: My App
```

???+ note "Platform-specific settings"

    Trapeze uses platform-specific keys for similar settings. For example, Android uses `packageName` while iOS uses `bundleId`. Refer to the [Android](https://trapeze.dev/docs/Operations/android){:target="_blank"} and [iOS](https://trapeze.dev/docs/Operations/ios){:target="_blank"} operation guides for complete lists of available settings.

### Build Script

Add an npm script to your `package.json` that runs Trapeze for Android and iOS platforms before the web build process:

```json
{
  "scripts": {
    "capawesome:build": "if [ \"$CI_PLATFORM\" = \"ios\" ] || [ \"$CI_PLATFORM\" = \"android\" ]; then npx trapeze run capawesome.yml -y --$CI_PLATFORM; fi && npm run build"
  }
}
```

Capawesome Cloud automatically calls the [web build script](web-build-script.md) during the build process. The script conditionally runs Trapeze only for iOS and Android platforms using the `$CI_PLATFORM` environment variable.

### Using Environment Variables

You can use Capawesome Cloud's [environment variables](environments.md) to dynamically configure your native projects. This is particularly useful for overwriting settings based on your build environment.

#### Define Variables

First, define variables in your Trapeze configuration file:

```yaml
vars:
  APP_ID:
  APP_NAME:

platforms:
  android:
    packageName: $APP_ID
    appName: $APP_NAME
  ios:
    bundleId: $APP_ID
    displayName: $APP_NAME
```

#### Set Variable Values

Then, set the variable values in your Capawesome Cloud environment:

1. Navigate to the [Environments](https://console.cloud.capawesome.io/apps/_/environments){:target="_blank"} page
2. Select your environment or create a new one
3. Add variables with their values:
   - `APP_ID`: `com.example.myapp`
   - `APP_NAME`: `My App`

You can create multiple environments with different values (e.g., development, staging, production) and select the appropriate environment when triggering a build.

???+ tip "Default values"

    You can provide default values for variables that will be used if no environment variable is set:

    ```yaml
    vars:
      APP_ID:
        default: com.example.default
      APP_NAME:
        default: Default App Name
    ```

## Next steps

- [Trigger a build](builds.md) — select a native configuration when you start a build.
- [Set up environments](environments.md) — the variables and secrets available during a build.
- [Auto-increment build numbers](auto-incrementing-build-numbers.md) — keep version codes and build numbers unique.
- [API](../api.md) — manage native configurations programmatically at `/v1/apps/{appId}/configurations`.