Documentation

App Store Connect Setup Guide

Configure your Apple Developer account for automatic builds

Prerequisites

  • Apple ID: A valid Apple ID with Two-Factor Authentication enabled.
  • Developer Program Membership: You must be enrolled in the Apple Developer Program ($99/year). This is required to distribute apps on the App Store.

Step 1: Register your App ID

Before we can build your app, Apple needs to know it exists. You must register the Bundle ID on the Developer Portal.

  1. Go to Certificates, Identifiers & Profiles.
  2. Click the (+) button next to Identifiers.
  3. Select App IDs and click Continue.
  4. Select App and click Continue.
  5. Enter a Description (e.g., "My Web App").
  6. For Bundle ID, select "Explicit" and enter your unique identifier (e.g., com.yourcompany.appname).
    Important: This MUST match the Bundle ID you enter in the WebToApp dashboard.
  7. Enable Capabilities - scroll down to the Capabilities section and enable:
    • Associated Domains — required if your app has a website URL (see Step 2)
    • App Groups — required if OneSignal is enabled (see Step 3)
    • Push Notifications — required if OneSignal is enabled
  8. Click Continue and then Register.

If the App ID already exists, open it in the portal and confirm these capabilities are enabled before your first App Store build.

Step 2: Enable Associated Domains (required if your app has a website URL)

WebToApp apps load your website inside the native shell. When a website URL is configured in the dashboard, the iOS build adds Universal Links so links to your domain can open in the app. That requires the Associated Domains capability on your main App ID and in the App Store provisioning profile.

App ID to configure: <your-bundle-id>

Associated Domains added to the app at build time:

  • applinks:<your-domain.com>
  • applinks:www.<your-domain.com>

The build script derives these from your dashboard URL (with and without www). No domain list is entered in the Apple portal — only the capability toggle.

What the build does automatically

  • Enables Associated Domains on your App ID via the App Store Connect API
  • Regenerates the App Store provisioning profile (with retries if Apple is slow to propagate)
  • Injects the applinks: entries into Runner.entitlements

If the build fails with "doesn't support the Associated Domains capability"

This usually means the capability was just enabled and the profile was generated before Apple updated it. Fix it manually once, then re-run the build:

  1. Go to Apple Developer Portal → Identifiers
  2. Open <your-bundle-id> (your main app, not the OneSignal extension)
  3. Under Capabilities, enable Associated Domains → Save
  4. Re-run the iOS build — provisioning profiles will regenerate with the entitlement

Skip this step only if your app has no website URL in the dashboard (no Universal Links are configured).

Step 3: Configure App Group (required if OneSignal is enabled)

If you use OneSignal push notifications, Apple requires a dedicated App Group so the main app and the notification service extension can share data. This is a one-time setup per app in the Apple Developer Portal — the build cannot create it automatically.

Expected App Group identifier: group.<your-bundle-id>.onesignal

Format: group.<your-bundle-id>.onesignal — the middle segment must match your iOS Bundle ID in this dashboard exactly.

2a. Create the App Group

  1. Go to Apple Developer Portal → App Groups.
  2. Click the (+) button to register a new App Group.
  3. Enter:
    • Description: any label (e.g. your app name + " OneSignal")
    • Identifier: group.<your-bundle-id>.onesignal (copy exactly — do not change the format)
  4. Click Continue → Register.

2b. Assign the App Group to both App IDs

The App Group must be enabled on both bundle identifiers below. If the NSE identifier does not exist yet, it is created automatically on your first iOS build with OneSignal — you can assign the App Group to it after that build attempt, then re-run the build.

  1. Go to Identifiers → App IDs.
  2. Open your main app identifier (your Bundle ID from Step 1) → scroll to App Groups → Edit or Configure → check group.<your-bundle-id>.onesignal → Save.
  3. Open <your-bundle-id>.OneSignalNotificationServiceExtension → App Groups → Edit or Configure → check the same group.<your-bundle-id>.onesignal → Save.

After saving, re-run your iOS build. Provisioning profiles are regenerated and will include the App Group.

Step 4: Create App on App Store Connect

Now create the app listing on App Store Connect so you can upload builds.

  1. Go to App Store Connect → Apps.
  2. Click the (+) button and select New App.
  3. Fill in the details:
    • Platforms: iOS
    • Name: Your app's display name
    • Primary Language: Select your primary language
    • Bundle ID: Select the Bundle ID you created in Step 1
    • SKU: A unique identifier for your app (e.g., myapp-001)
    • User Access: Full Access (recommended)
  4. Click Create.
Note: After creating the app, you can optionally set up TestFlight groups, add metadata, and configure App Store listing details.

Step 5: Create App Store Connect API Key

WebToApp uses this key to automatically manage certificates, profiles, and upload your build.

  1. Go to App Store Connect > Users and Access > Integrations > App Store Connect API.
  2. Click the (+) button to generate a new API Key.
  3. Enter a name (e.g., "WebToApp Builder").
  4. Access: Select Admin.
    Why Admin? We need this permission to automatically create provision profiles and certificates for you. Without it, the build will fail.
  5. Click Generate.

Step 6: Download Credentials

Once the key is created, you need to gather three pieces of information for the WebToApp dashboard:

1. Issuer ID
Found at the top of the Keys page. UUID format.
2. Key ID
10-character ID shown in the key list row.
3. Team ID
Found on your Membership Details page. 10-character alphanumeric ID.
4. Private Key (.p8 file)
Click "Download API Key" next to your key.
⚠️ Warning: You can only download this file ONCE. Keep it safe!

Step 7: Configure WebToApp

Return to the iOS Tab in the dashboard and enter the credentials you just gathered.

Troubleshooting

Error: "App ID not found on Developer Portal"

You need to create the App ID on the Apple Developer Portal before building. Follow Step 1 above. Make sure the Bundle ID in the WebToApp dashboard matches exactly what you registered.

Error: "Bundle identifier not available"

This usually means someone else has already taken this Bundle ID. You must choose a different, unique ID in the Apple Developer Portal and update it here.

Error: "Team ID mismatch"

Ensure you copied the Team ID from your Membership Details page, not the Header of some other page.

Error: Associated Domains / Universal Links provisioning profile

Your app uses Universal Links (from your website URL). Complete Step 2: Associated Domains — enable the capability on <your-bundle-id> — then re-run the build.

Error: App Group missing from provisioning profile

This happens when OneSignal is enabled but the App Group was not created or not assigned to both App IDs. Complete Step 3 above — your identifier must be exactly group.<your-bundle-id>.onesignal — then re-run the build.

Push Notifications not working

Make sure you enabled the Push Notifications capability when creating your App ID. You can edit the App ID later at Certificates, Identifiers & Profiles.