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

# Build Settings

> Complete reference for capwrap.config.json — app metadata, appearance, permissions, and third-party integration settings for every build.

Every build setting in Capwrapper can be configured through a `capwrap.config.json` file placed in your project root, or through the CapWrapPro dashboard UI. Both methods map to the same keys, so you can start in the dashboard and graduate to file-based config at any point in your workflow.

<Note>
  When both dashboard settings and `capwrap.config.json` are present, the JSON file takes precedence.
</Note>

## App metadata

App metadata controls how your app is identified and presented across device home screens, the app switcher, and store listings. These are the fields most likely to affect your store approval and user experience.

<ParamField body="appName" type="string" required>
  The display name shown on the device home screen, in the app switcher, and in store listings. This is what users see after installing your app. Keep it concise — most devices truncate names beyond 12–15 characters.

  **Example:** `"My Finance App"`

  <Tip>
    Choose a name that is unique and recognisable. Avoid generic names like "My App" — app stores may flag them during review.
  </Tip>
</ParamField>

<ParamField body="appVersion" type="string" required>
  The semantic version string for this build, following `major.minor.patch` format (semver). Both the Play Store and App Store require each new submission to have a higher version number than the previous one. Capwrapper automatically derives the numeric version code from this string.

  **Example:** `"1.2.0"`

  <Warning>
    Submitting a build with a version number equal to or lower than the currently published version will be rejected by both app stores.
  </Warning>
</ParamField>

<ParamField body="packageId" type="string" required>
  The unique application identifier in reverse domain notation. Must be lowercase, contain only letters, numbers, and periods, and include at least two segments (e.g. `com.example`).

  **Example:** `"com.acmecorp.financeapp"`

  <Warning>
    `packageId` cannot be changed after your first production release. A different package ID creates a completely separate app listing in the store — your existing users will not receive updates.
  </Warning>
</ParamField>

<ParamField body="description" type="string">
  A short description of your app used in store listings and metadata. Keep it under 80 characters for optimal display across all store surfaces. This is the first thing prospective users read, so make it specific and action-oriented.

  **Example:** `"Track expenses, manage budgets, and view financial reports on the go."`
</ParamField>

<ParamField body="author" type="string">
  The developer or company name used in store metadata and the app's About section. On the Play Store this appears as the developer name. On the App Store it maps to the provider field.

  **Example:** `"Acme Corporation"`
</ParamField>

## Appearance

The appearance section controls the visual identity of your app. You can customise:

* **App icon** — the icon shown on the home screen and in the app switcher
* **Splash screen** — the loading screen displayed while your app initialises
* **Custom colors and branding** — accent colors and theme settings applied across the native shell

These settings are configured in the dashboard's **Appearance** tab or via the corresponding keys in `capwrap.config.json`.

## Permissions

Permissions are declared at build time and presented to users as native permission prompts at runtime. Only declare permissions your app actually uses — app stores may reject builds that request permissions not justified by the app's functionality.

| Permission         | What it enables                                 |
| ------------------ | ----------------------------------------------- |
| Camera             | QR scanning, document scanning, image capture   |
| Location / GPS     | Maps integration, background location tracking  |
| Push notifications | Requires Firebase setup (see Integrations)      |
| Microphone         | Voice input and audio recording                 |
| Contacts           | Reading device contacts (name and phone number) |
| Calendar           | Adding events to the device calendar            |
| Health data        | Step count via Apple Health or Google Fit       |
| Storage / Files    | File download and upload from device storage    |

## Integrations

Capwrapper supports the following third-party integrations, each configurable via `capwrap.config.json` or the dashboard:

* **Firebase** — enables push notifications (via FCM) and Firebase Analytics event logging
* **RevenueCat** — powers in-app purchases and subscription management through the `NativeInAppPurchase` bridge
* **Google AdMob** — delivers banner, interstitial, and rewarded ads via the `NativeAdMob` bridge
* **Google Sign-In, Facebook, Apple Sign-In** — native social authentication via the `NativeSocialLogin` bridge

Each integration requires its own credentials (API keys, service account files, or provisioning configuration). You supply these in the dashboard under **Integrations** or as fields in the config file.

## Example config

The following is a minimal working `capwrap.config.json` covering the core app metadata fields:

```json capwrap.config.json theme={null}
{
  "appName": "My Finance App",
  "appVersion": "1.2.0",
  "packageId": "com.acmecorp.financeapp",
  "description": "Track expenses and manage budgets on the go.",
  "author": "Acme Corporation"
}
```

Place this file in the root of your project. Capwrapper will detect it automatically at build time and merge it with any settings saved in the dashboard, with the file taking precedence.