AppStore iOS

A step-by-step guide to publishing your Lovable web app as a native iOS app using Despia

Before You Start: Prerequisites

What You'll Need

  • Published Lovable project (your web app must be live)

  • Apple Developer Account ($99/year)

  • Despia account (offers free demo build)

  • App assets (1024x1024 icon, splash screen GIF)

  • 2-3 hours of focused time for initial setup

Phase 1: Basic Setup

1

Prepare Your Lovable Project

  1. Ensure your Lovable project is published

    • Your web app must be live and accessible

    • Copy the published URL from your Lovable editor

    • Test that the URL works properly

2

Create Your Despia Account

  1. Go to Despia.com and sign up

  2. Claim your free demo build - Despia offers one free test build

  3. This covers all cloud resources for your first attempt

3

Create New Application in Despia

  1. Click "Create New Application"

  2. App Name: Use no spaces or special characters (e.g., "iOSMaster")

  3. Web App Start URL: Paste your Lovable published URL

  4. Bundle ID: Choose format com.yourcompany.appname (e.g., com.despia.iosmaster)

  5. Click "Create New Application"

4

Design Your App Assets

App Icon Requirements

  • Size: Exactly 1024x1024 pixels

  • Format: PNG (no transparency, no rounded corners)

  • Tools: Use Canva, Figma, or any design tool

  • Upload to Despia's icon section

Splash Screen Requirements

  • Size: Exactly 1024x1024 pixels

  • Format: GIF with transparent background

  • Purpose: Shows when app starts loading

  • Can be animated or static

  • Upload to Despia's splash screen section

Critical: Wrong dimensions will cause build failures!

Phase 2: Apple Developer Account Integration

1

Link Your Apple Developer Account to Despia

Get API Credentials from App Store Connect

  1. Go to appstoreconnect.apple.com

  2. Navigate to Users and Access

  3. Go to Integrations tab

  4. Click the "+" to create new integration

  5. Name: "Despia" or "Despia CICD"

  6. Role: Must be "App Manager" (not Admin, not Developer)

  7. Click "Generate"

Collect Required Information

You need to gather three pieces of information:

1. Issuer ID

  • Found at top of App Store Connect integrations page

  • Copy this ID

2. Key ID

  • From your newly created API key

  • Copy the Key ID (not the key itself)

3. Development Team ID

  • Go to developer.apple.com

  • Click "Certificates, Identifiers & Profiles"

  • Your Team ID is in the top right corner next to your company name

4. P8 Key File

  • Download the P8 file from App Store Connect

  • Warning: You can only download this once!

  • Store it safely - Despia will store it for you after upload

Add Account in Despia

  1. In Despia, click "Add New Developer Account"

  2. Enter Account Issuer ID

  3. Enter Connect API Key ID

  4. Upload the P8 key file

  5. Enter Development Team ID

  6. Click "Link with Apple"

  7. Select your developer account in the dropdown

Phase 3: Bundle ID Registration (Most Critical Section)

1

Register Your Main Bundle ID

This is where most people fail. Follow exactly:

  1. Go to developer.apple.com

  2. Click "Certificates, Identifiers & Profiles"

  3. Select "Identifiers" → "+"

  4. Choose "App IDs" → "Continue"

  5. Select "App" → "Continue"

  6. Description: Your app name (e.g., "iOS Master")

  7. Bundle ID: Use the exact ID from Despia (e.g., com.despia.iosmaster)

  8. Capabilities: Enable these essential ones:

    • App Attest

    • App Groups

    • Associated Domains

    • iCloud (with CloudKit support)

    • Push Notifications

    • Background App Refresh

  9. Click "Continue" → "Register"

2

Understanding External Bundle Requirements

Why External Bundles Are Required: Despia uses a modular system. Even if you don't plan to use push notifications, widgets, or app clips, you MUST register these "external bundles" or your build will fail. Think of them as optional features that need to be registered even when disabled.

External bundles you must register:

  1. OneSignal Bundle (for push notifications)

  2. App Clip Bundle (for app clips)

  3. Share Bundle (for sharing functionality)

  4. Widget Bundle (for smart widgets)

Each external bundle needs:

  • Its own Bundle ID registration

  • Its own App Group registration

  • Proper linking between bundle and app group

  • Connection to your main app

3

External Bundle Registration Process

You'll repeat this process 4 times - once for each external bundle

Part A: Register the External Bundle ID

For OneSignal Bundle (Example - repeat for others):

  1. In Despia, copy the OneSignal Bundle ID from the targets section

  2. Go to developer.apple.com → "Identifiers" → "+"

  3. Choose "App IDs" → "Continue"

  4. Select "App" → "Continue"

    • Exception: For App Clip Bundle, select "App Clip" instead

  5. Description: "iOS Master OneSignal Bundle" (use your app name)

  6. Bundle ID: Paste the exact OneSignal Bundle ID from Despia

  7. Capabilities for OneSignal Bundle:

    • App Groups (required for all external bundles)

    • Associated Domains

    • Push Notifications

    • Background App Refresh

  8. Click "Continue" → "Register"

Special Case - App Clip Bundle:

  • When creating App Clip Bundle, select "App Clip" not "App"

  • Parent App ID: Select your main bundle ID

  • Product Name: Must be exactly "Clip" (capital C)

  • Capabilities: App Groups, Associated Domains, Push Notifications

Capabilities for Each Bundle Type:

  • OneSignal: App Groups + Associated Domains + Push Notifications + Background App Refresh

  • App Clip: App Groups + Associated Domains + Push Notifications

  • Share: App Groups only

  • Widget: App Groups only

Part B: Register the App Group for This Bundle

  1. In Despia, copy the App Group ID for the same bundle (starts with "group.")

  2. Go to developer.apple.com → "Identifiers" → "+"

  3. Choose "App Groups" → "Continue"

  4. Identifier: Paste the App Group ID from Despia

  5. Description: "iOS Master OneSignal App Group" (match the bundle type)

  6. Click "Continue" → "Register"

Part C: Link the Bundle to Its App Group

  1. Go to "Identifiers" → search for your app name

  2. Find and click on the OneSignal Bundle you just created

  3. Scroll to "App Groups" capability

  4. Click "Configure"

  5. Search for your app name (Command+F: "iOS Master")

  6. Select ONLY the OneSignal App Group (the one that matches this bundle)

  7. Click "Continue" → "Save"

Critical: OneSignal Bundle links to OneSignal App Group ONLY. Don't mix them up.

Part D: Link Your Main App to All App Groups

Do this AFTER registering all external bundles:

  1. Go to "Identifiers" → search for your app name

  2. Click on your main app bundle ID (not the external ones)

  3. Scroll to "App Groups" capability

  4. Click "Edit"

  5. Search for your app name

  6. Select ALL app groups for your application:

    • iOS Master OneSignal App Group

    • iOS Master App Clip App Group

    • iOS Master Share App Group

    • iOS Master Widget App Group

  7. Click "Continue" → "Save"

4

Repeat for All External Bundles

Repeat Steps 8A-8C for each external bundle:

  1. OneSignal Bundle + OneSignal App Group (done above)

  2. App Clip Bundle + App Clip App Group

  3. Share Bundle + Share App Group

  4. Widget Bundle + Widget App Group

Then complete Step 8D once to link your main app to all app groups.

Visual Overview of What You're Creating:

Main App Bundle (com.yourcompany.appname)
├── Links to: OneSignal AppGroup
├── Links to: AppClip AppGroup  
├── Links to: Share AppGroup
└── Links to: Widget AppGroup

OneSignal Bundle (com.yourcompany.appname.OneSignalNotificationServiceExtension)
└── Links to: OneSignal AppGroup (ONLY) - (group.com.yourcompany.appname.onesignal)

AppClip Bundle (com.yourcompany.appname.Clip)
└── Links to: AppClip AppGroup (ONLY) - (group.com.yourcompany.appname.Clip)

Share Bundle (com.yourcompany.appname.ShareExtensionTarget)
└── Links to: Share AppGroup (ONLY) - (group.com.yourcompany.appname.sharetarget)

Widget Bundle (com.yourcompany.appname.ImageWidget)
└── Links to: Widget AppGroup (ONLY) - (group.com.yourcompany.appname.widgetsharing)

Phase 4: App Store Connect Setup

1

Create App Store Listing

  1. Return to appstoreconnect.apple.com

  2. Go to "My Apps" → "+" → "New App"

  3. Platform: iOS

  4. Name: Your app's display name

  5. Primary Language: English (US)

  6. Bundle ID: Select your main registered bundle ID

  7. SKU: Your app name in caps, no spaces (e.g., "IOSMASTER")

  8. User Access: Full Access

  9. Click "Create"

2

Get App Store Listing ID

  1. In your new app, go to "App Information"

  2. Under "General Information", find the Apple ID

  3. Copy this Apple ID number - you'll need it for Despia

  4. Go back to Despia and paste this ID in the Build Configuration section

3

Set Up TestFlight

  1. In App Store Connect, go to your app → "TestFlight"

  2. Click "Internal Testing" → "+"

  3. Group Name: "Internal"

  4. Add Testers: Enter your email address

  5. Create

Phase 5: Building and Testing

1

Final Checks Before Building

Verify everything is set up correctly:

  • Main bundle ID registered with proper capabilities

  • All 4 external bundle IDs registered

  • All 4 app groups registered

  • Each external bundle linked to its matching app group

  • Main app linked to ALL app groups

  • Apple Developer account linked in Despia

  • App Store listing ID entered in Despia

  • App icon and splash screen uploaded

2

Configure App Settings (Optional)

In Despia, you can configure:

  • Full Screen Mode: Enable for immersive experience

  • Status Bar: Set colors to match your splash screen

  • Add-ons: Enable features like Face ID, location tracking if needed

  • Associated Domains: Always enable this

3

Build Your App

Only after everything is configured:

  1. Click "Publish Project" in Despia

  2. The build process begins on Apple M2 Mac machines

  3. Wait 5-20 minutes for completion

  4. You'll receive email notifications about build status

During the build, don't close the browser or make changes

4

Test on TestFlight

Once the build completes successfully:

  1. Check your email for Apple's build completion notification

  2. Click "View in TestFlight" from the email

  3. Install the TestFlight app if you haven't already

  4. Install your app through TestFlight

  5. Test all functionality thoroughly

Note: Development builds show a watermark and license notice. This is normal for testing.

Phase 6: Adding Native Features

Despia SDK Integration Guide

Use this exact prompt pattern in Lovable for any native feature:

Lovable Prompt
Lovable Prompt

Add native [FEATURE] functionality using the Despia SDK from: https://www.npmjs.com/package/despia-native

First, install the package: npm install despia-native

Then import it: import despia from 'despia-native'

[Specific implementation instructions]

Please follow the installation instructions for the "despia-native" npm package closely, and do not modify my instructions. Implementation as mentioned is critical.

Contact Access Example

Lovable Prompt:

Lovable Prompt
Lovable Prompt

Add native contact access functionality to retrieve users' device contacts including names and phone numbers using the Despia SDK from: https://www.npmjs.com/package/despia-native

First, install the package: npm install despia-native

Then import it: import despia from 'despia-native'

1. Request contact permission using despia("requestcontactpermission://")

2. Read contacts using await despia('readcontacts://', ['contacts']) which returns a JSON object with contact names as keys and phone number arrays as values

3. When accessing the data, use "dot notation" like .contacts to retrieve the contact data in a JSON object format

Please follow the installation instructions for the "despia-native" npm package closely, and do not modify my instructions. Implementation as mentioned is critical.

Expected Implementation:

import despia from 'despia-native';

// Request permission first
await despia("requestcontactpermission://");

// Read contacts data
const contactsData = await despia('readcontacts://', ['contacts']);
console.log(contactsData.contacts);

// Expected output format:
{
  "John Appleseed": ["+12345678910"],
  "Ann Wilson": ["+12345678910"]
}

Testing Native Features

  1. Make changes in your Lovable project

  2. Publish your Lovable project

  3. Over-the-air updates: Your TestFlight app updates automatically!

  4. Test permissions: iOS will prompt for permissions on first use

  5. No rebuild needed unless changing app configuration

Phase 7: Publishing to App Store

1

Complete App Store Listing

While testing your app, complete your App Store Connect listing:

Required Information

  1. App Information

    • Category: Choose most appropriate

    • Content Rights: Describe content ownership

    • Age Rating: Complete questionnaire

  2. Pricing and Availability

    • Price: Free or paid

    • Availability: Select countries/regions

    • Release date: Automatic or manual

  3. App Privacy

    • Privacy Policy: Required for all apps

    • Data Collection: Describe what data you collect

    • Data Usage: Explain how you use collected data

  4. App Store Listing

    • Description: Up to 4,000 characters explaining your app

    • Keywords: Relevant search terms (100 characters max)

    • Support URL: Link to your support page

    • Screenshots: 3-10 screenshots showing app features

2

Upgrade to Production License

To remove watermarks and publish commercially:

  1. In Despia, click "Build Production Version"

  2. Choose license type:

    • iOS Only: $249

    • Android Only: $249

    • iOS + Android: Higher tier pricing

  3. Benefits include:

    • No watermarks

    • Commercial publishing rights

    • Full source code export

    • Lifetime runtime updates

    • One-click App Store deployment

3

Submit for App Store Review

  1. In App Store Connect, go to your app

  2. Click "1.0 Prepare for Submission"

  3. Build section: Select your Despia-built version

  4. App Review Information: Provide contact details

  5. Version Release: Choose automatic or manual

  6. Review all sections for completeness

  7. Click "Submit for Review"

Troubleshooting Common Issues

Build Failures

"Bundle ID not found"

  • Ensure all bundle IDs are registered in Apple Developer

  • Check that bundle IDs match exactly between Despia and Apple

  • Verify main bundle ID is registered first

"Provisioning profile error"

  • Verify Apple Developer account is properly linked in Despia

  • Confirm API key has "App Manager" role, not Admin or Developer

  • Check that Development Team ID is correct

"App Groups configuration failed"

  • Most common error - check these carefully:

  • Each external bundle links to its own app group (OneSignal → OneSignal group)

  • Main app links to ALL app groups

  • No mixing of app groups between bundles

  • All app groups are properly registered

"External bundle registration incomplete"

  • You must register ALL 4 external bundles even if unused

  • Missing any external bundle will cause build failure

  • Double-check: OneSignal, App Clip, Share, Widget

TestFlight Issues

"App not appearing in TestFlight"

  • Check that build completed successfully in Despia

  • Verify you're added to internal testing team

  • Look for Apple's email notifications

"App crashes on startup"

  • Check status bar color settings in Despia

  • Ensure splash screen is proper format and size (1024x1024 GIF)

  • Verify full screen mode setting matches your design

External Bundle Linking Errors

"Failed to link app groups"

  • Search by your app name in Apple Developer to find all your items

  • Ensure consistent naming: "iOS Master OneSignal Bundle" + "iOS Master OneSignal App Group"

  • OneSignal bundle should only link to OneSignal app group

  • Main app should link to ALL app groups

"App Clip registration failed"

  • App Clip bundle must be registered as "App Clip" type, not "App"

  • Parent App ID must be your main bundle ID

  • Product Name must be exactly "Clip" with capital “C”

Cost Summary

Required Costs

  • Apple Developer Account: $99/year

  • Despia Production License: Starting at $249 (for commercial publishing)

Optional Costs

  • Additional Despia Build Credits: $25+ for extra development credits

  • Design Tools: Canva Pro, Figma, etc. (optional)

Free Tier Includes

  • One free development build with Despia

  • Unlimited over-the-air updates to your Lovable app

  • TestFlight testing with development watermark

Support and Resources

Getting Help

  • Despia Support: 24/7 support with <2 minute response times

  • Free Expert Help: Available if you encounter issues with your free build

  • External Bundle Help: Most common issue - contact support for guidance

Important Links

Remember: The external bundle registration process is the most critical and complex part. Take your time with Phase 3 - getting this right the first time saves you from wasting your free build credit. Most build failures happen because of incomplete external bundle setup, not because of your actual app code.

Updated on
How it Works
GooglePlay Android