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

# Bundle IDs, Permissions, and App Signing

> How to choose and format your bundle ID, which permissions to declare, and how to supply signing credentials for Android and iOS builds in Capwrapper.

Before you submit your first build, there are three configuration decisions you need to get right: your bundle ID, the permissions your app declares, and the signing credentials you supply for each platform. Getting these wrong can block store approval or require you to start a new app listing from scratch — so this page covers each one in detail.

## Bundle ID

A bundle ID (also called a package ID on Android) is the globally unique identifier for your app in the store ecosystem. It is written in reverse domain notation and follows this pattern: `com.yourcompany.appname`.

### Format rules

* Must be **lowercase**
* May contain only **letters, numbers, and periods**
* Must have **at least two segments** separated by a period (e.g. `com.example` is valid; `myapp` is not)
* Should reflect your organisation and app name to aid discoverability and avoid conflicts

**Valid examples:**

```
com.acmecorp.financeapp
io.yourcompany.crm
com.example.myapp
```

### Choosing your bundle ID

<Warning>
  Your bundle ID is permanent after your first production release. If you change it, the app stores treat it as a completely new, separate app — your existing users will not receive updates, and your store listing history starts over. Choose carefully before your first submission.
</Warning>

Use a domain you own to guarantee uniqueness. If your website is `acmecorp.com`, your bundle ID should start with `com.acmecorp`. Avoid using generic prefixes like `com.example` or `com.app` in production builds.

## Permissions

Permissions are declared at build time as part of your app manifest. Users are prompted to grant or deny each permission at runtime — typically when they first trigger a feature that requires it.

Only declare permissions your app actually uses. Both the App Store and Google Play review processes may reject builds that request permissions without clear justification in the app's functionality.

### Available permissions

| Permission         | What it enables                                                       |
| ------------------ | --------------------------------------------------------------------- |
| Camera             | QR code scanning, document scanning, and in-app image capture         |
| Location / GPS     | Map integrations and background location tracking                     |
| Push notifications | Sending alerts via Firebase Cloud Messaging — requires Firebase setup |
| Microphone         | Voice input and audio recording features                              |
| Contacts           | Reading the device contact list (name and phone number)               |
| Calendar           | Creating and adding events to the device calendar                     |
| Health data        | Accessing step count via Apple Health or Google Fit                   |
| Storage / Files    | Downloading files to device storage and uploading files from it       |

<Note>
  Permissions are declared at build time and presented to users as native system prompts at runtime. You do not need to write any code to trigger these prompts — Capwrapper handles the native permission request flow automatically.
</Note>

## App signing

Every app submitted to the App Store or Google Play must be signed with a cryptographic certificate. Signing proves the binary came from you and has not been tampered with. Capwrapper handles the signing step using the credentials you supply.

### Android signing

Android builds use a keystore file to sign the APK and AAB.

**For testing:** Capwrapper generates an auto-signed debug keystore automatically. You can install and run debug builds on any device without supplying your own keystore.

**For Play Store submissions:** You must use your own keystore. Generate one with the following command:

```bash theme={null}
keytool -genkey -v -keystore my-release-key.jks -alias mykey -keyalg RSA -keysize 2048 -validity 10000
```

Upload the resulting `.jks` file, your key alias, and your key password in the Capwrapper dashboard under **Settings → Android Signing** before triggering a production build.

<Warning>
  Keep your keystore file and passwords in a safe place. If you lose your keystore, you cannot update your existing Play Store listing — you would need to publish under a new package ID.
</Warning>

### iOS signing

iOS builds require:

* An **Apple Developer account** (individual or organisation, enrolled in the Apple Developer Program)
* A **distribution certificate** issued from App Store Connect
* A **provisioning profile** tied to your app's bundle ID and distribution certificate

You generate these in [App Store Connect](https://appstoreconnect.apple.com) and Xcode's certificate management tools, then upload them to the Capwrapper dashboard under **Settings → iOS Signing**.

<Tip>
  If you are new to iOS certificates and provisioning profiles, Apple's documentation on code signing is the most reliable reference. The setup is a one-time process — once your credentials are in the dashboard, all future builds use them automatically.
</Tip>

Capwrapper uses your supplied credentials to sign the IPA during the cloud build. You do not need Xcode or a Mac to complete this step.