Bundle Identifier

Definition

A bundle identifier is the reverse-DNS string, such as com.example.shop, that uniquely identifies an iOS app to the operating system and the App Store.

Android's equivalent is the package name, and the two are close enough that teams treat them as one field and then spend an afternoon working out why a deep link or an install postback matches nothing. They are set in different places, allowed to differ from each other, and appear under different names in every attribution payload you will read.

The three identifiers people call the same thing

The column that catches people is the fourth. iOS authorises by App ID — prefix included — while Android authorises by package name plus certificate fingerprint. Neither platform accepts the other's identifier, and a config file that carries the wrong one is well-formed and inert.

Where each one is configured

On iOS the bundle identifier is a build setting, which means it can vary per configuration. On Android there are two similar-looking Gradle properties, and only one of them is the app's identity.

android {
    // The Java/Kotlin package for generated sources (R, BuildConfig).
    // NOT the app's identity. Renaming it changes nothing publicly.
    namespace = "com.example.shop"

    defaultConfig {
        // The app's identity on the device and on Play.
        // This is the value assetlinks.json must contain.
        applicationId = "com.example.shop"
    }

    buildTypes {
        debug {
            // Debug installs alongside release as a SEPARATE app:
            // com.example.shop.debug
            applicationIdSuffix = ".debug"
        }
    }
}

The iOS equivalent is a per-configuration bundle identifier, usually com.example.shop.dev for a Debug build. It needs its own App ID, its own Associated Domains capability, and its own entry in the appIDs array — which is why that array so often has three entries.

How each appears in attribution data

Every attribution system keys on one of these strings, and almost none of them agree on what to call the field. When an install postback matches no app, this table is usually where the answer is.

# iOS: from an .ipa
unzip -p Shop.ipa "Payload/*.app/Info.plist" | \
  plutil -extract CFBundleIdentifier raw -

# Android: from an APK or AAB
aapt2 dump badging app-release.apk | head -1

# Android: what is actually installed on the device
adb shell pm list packages | grep example

Choosing one, and living with it

The rules are short, and the cost of breaking them is a new App Store listing with no reviews and no ranking.

• Reverse-DNS from a domain you control: com.example.shop, not shop or MyApp.
• Letters, digits, hyphens and dots on iOS; Android additionally requires each dot-separated segment to start with a letter and forbids hyphens.
• Keep iOS and Android identical unless you have a reason not to — every dashboard, export and support conversation is easier when there is one string.
• Never reuse an identifier from a deleted app; on both stores it stays claimed.
• Once an app is published, it is permanent. Changing it publishes a new app, and existing users are not migrated.

If you have inherited a mismatch — say com.example.shop on iOS and com.example.shopapp on Android — do not rename. Record both in your attribution configuration and in both association files, and move on. The rename costs more than the inconsistency.