> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobile-starter.amisi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# App Identity Configuration

> Configure your app name, bundle identifiers, and URL scheme

## Configuration Files

App identity is managed in two files:

* **`amisi.config.json`** - Source of truth for app identity
* **`apps/mobile/app.json`** - Expo configuration (synced from amisi.config.json)

## Using the Configurator (Recommended)

The easiest way to configure app identity is through the Configurator UI:

1. Start the Configurator:

```bash theme={null}
bun run configurator:dev
```

2. Navigate to the **App** section

3. Edit the identity fields:
   * App name
   * URL scheme
   * iOS bundle identifier
   * Android package name

4. Click **Save** to persist changes

5. Click **Apply** to write changes to `app.json`

## Manual Configuration

Edit `amisi.config.json` at the repository root:

```json theme={null}
{
  "appIdentity": {
    "name": "Your App Name",
    "scheme": "your-app-scheme",
    "iosBundleIdentifier": "com.yourcompany.yourapp",
    "androidPackage": "com.yourcompany.yourapp"
  }
}
```

### Field Requirements

#### App Name

* Display name shown to users
* Used in app stores and device home screen
* Can contain spaces and special characters

#### URL Scheme

* Used for deep linking
* Must be lowercase
* No spaces or special characters
* Example: `myapp`, `my-app`

#### iOS Bundle Identifier

* Reverse domain notation
* Must be unique in the App Store
* Format: `com.company.appname`
* Cannot be changed after first App Store submission

#### Android Package Name

* Reverse domain notation
* Must be unique in Google Play Store
* Format: `com.company.appname`
* Cannot be changed after first Play Store submission

## Syncing to app.json

After editing `amisi.config.json`, sync changes to `app.json`:

### Using Configurator

The Configurator automatically syncs when you click **Apply**.

### Manual Sync

If editing manually, update the corresponding fields in `apps/mobile/app.json`:

```json theme={null}
{
  "expo": {
    "name": "Your App Name",
    "slug": "your-app-slug",
    "scheme": "your-app-scheme",
    "ios": {
      "bundleIdentifier": "com.yourcompany.yourapp"
    },
    "android": {
      "package": "com.yourcompany.yourapp"
    }
  }
}
```

## Important Notes

### Bundle Identifier Best Practices

* **Use your domain**: `com.yourdomain.appname`
* **Be consistent**: Use the same identifier across iOS and Android when possible
* **Plan ahead**: Cannot change after first store submission
* **Avoid conflicts**: Check that your identifier isn't already in use

### URL Scheme Best Practices

* **Keep it simple**: Short, memorable schemes work best
* **Match your brand**: Use your app or company name
* **Check availability**: Ensure the scheme isn't used by popular apps
* **Use hyphens**: For multi-word schemes (e.g., `my-app`)

## Testing Changes

After changing app identity:

1. **Clean native projects**:

```bash theme={null}
bun run clear
```

2. **Rebuild**:

```bash theme={null}
bun run prebuild
```

3. **Run the app**:

```bash theme={null}
bun run ios
# or
bun run android
```

## EAS Configuration

If using EAS builds, ensure your EAS project is linked:

```bash theme={null}
cd apps/mobile
eas init
```

The EAS project ID will be added to `app.json` automatically.

## Common Issues

### Bundle Identifier Mismatch

If you see signing errors, ensure the bundle identifier in `app.json` matches your Apple Developer account provisioning profiles.

### Scheme Conflicts

If deep links don't work, check that your URL scheme doesn't conflict with other installed apps.

### Package Name Already Exists

If Google Play rejects your package name, it may be in use by another app (even if unpublished). Choose a different name.

## Next Steps

* [Configure Branding](/configuration/branding)
* [Set Up EAS](/configuration/eas-setup)