Migration Guide (V2 to V3)

Upgrade your Despia Runtime in just 30 Minutes with his Step-by-Step Guide

Overview

This guide provides step-by-step instructions for migrating your Despia application from version 2 to version 3. The migration process differs significantly between Android and iOS platforms.

Platform-Specific Requirements

Android Platform

No action required! Simply rebuild your application with automated publishing. Despia will handle everything automatically.

iOS Platform

iOS applications require manual configuration updates in your Apple Developer account. Follow the detailed steps below.

iOS Migration Process

Prerequisites

  • An existing Despia application successfully published with version 2

  • Access to your Apple Developer account

  • Understanding that Despia automatically uses the latest version when building

1

Update Core App Bundle ID Capabilities

  1. Navigate to your Apple Developer account

  2. Go to Identifiers → Find your app's core bundle ID

  3. Enable/verify the following capabilities:

    • App Attest

    • App Groups

    • Associated Domains (critical!)

    • iCloud (with CloudKit support - requires Xcode 6)

    • Push Notifications (Broadcast capability)

  4. Save changes and confirm modifications

2

Understanding the New Structure

Despia V3 introduces a modular approach with four new packages, each requiring:

  • A Bundle ID

  • An App Group

  • Proper linking between them

The four packages are:

  1. Push/OneSignal Target - For push notifications

  2. App Clip Target - For app clips (required even if unused)

  3. Share Target - For sharing functionality

  4. Widget Target - For smart widgets

3

Configure Push/OneSignal Target

Create Bundle ID:

  1. Go to Identifiers → + → App ID → Continue

  2. Select type: App

  3. Description: OneSignal Bundle ID for [Your App Name]

  4. Bundle ID: Copy from Despia editor's "Push Bundle ID"

  5. Enable capabilities:

    • App Groups

    • Push Notifications (Broadcast capability)

  6. Register the identifier

Create App Group:

  1. Go to Identifiers → + → App Groups → Continue

  2. Description: App Group for OneSignal for [Your App Name]

  3. Identifier: Copy from Despia editor's "Push App Group"

  4. Register the app group

Link Bundle ID to App Group:

  1. Find the OneSignal Bundle ID you just created

  2. Click App Groups → Configure

  3. Search (Cmd+F) for your app name

  4. Select the OneSignal app group

  5. Save and confirm

Link to Core Bundle ID:

  1. Go to your core app bundle ID

  2. Click App Groups → Configure

  3. Add the OneSignal app group

  4. Save and confirm

4

Configure App Clip Target

Create Bundle ID:

  1. Go to Identifiers → + → App ID → Continue

  2. Select type: App Clip (not App!)

  3. Parent App ID: Select your core bundle ID

  4. Product Name: Clip (must be exactly "Clip" with capital C)

  5. Description: App Clip Bundle ID for [Your App Name]

  6. Enable capabilities:

    • App Groups

    • Associated Domains (mandatory!)

    • Push Notifications (optional)

  7. Register the identifier

Create App Group:

  1. Create new App Group identifier

  2. Description: App Group for App Clip for [Your App Name]

  3. Identifier: Copy from Despia editor's "Clip App Group"

  4. Register the app group

Link Bundle ID to App Group:

  1. Configure the App Clip Bundle ID with its app group

  2. Link the app group to your core bundle ID

5

Configure Share Target

Create Bundle ID:

  1. Go to Identifiers → + → App ID → Continue

  2. Select type: App

  3. Description: Share Target Bundle ID for [Your App Name]

  4. Bundle ID: Copy from Despia editor's "Share Bundle ID"

  5. Enable capability: App Groups

  6. Register the identifier

Create App Group:

  1. Create new App Group identifier

  2. Description: App Group for Share Target for [Your App Name]

  3. Identifier: Copy from Despia editor's "Share App Group"

  4. Register and link as before

6

Configure Widget Target

Create Bundle ID:

  1. Go to Identifiers → + → App ID → Continue

  2. Select type: App

  3. Description: Widget Bundle ID for [Your App Name]

  4. Bundle ID: Copy from Despia editor's "Widget Bundle ID"

  5. Enable capability: App Groups

  6. Register the identifier

Create App Group:

  1. Create new App Group identifier

  2. Description: App Group for Widget for [Your App Name]

  3. Identifier: Copy from Despia editor's "Widget App Group"

  4. Register and link as before

7

Verification Checklist

Verify each component is properly configured:

For Each Target (OneSignal, App Clip, Share, Widget):

  • Bundle ID created with correct capabilities

  • App Group created

  • Bundle ID linked to its corresponding App Group

  • App Group linked to Core Bundle ID

Core Bundle ID Should Have:

  • All four App Groups linked

  • All required capabilities enabled

8

Clean Up Provisioning Profiles

  1. Go to Provisioning Profiles in Apple Developer

  2. Search for your app name

  3. Delete ALL provisioning profiles for your app

  4. Verify search returns "No results found"

9

Rebuild Your Application

  1. Return to Despia

  2. Click Publish App

  3. Despia will:

    • Use M2 build resources

    • Open Xcode and load your project

    • Compile over 2,100 native code files

    • Automatically sign with your Apple Developer account

    • Publish as draft to App Store

  4. Wait for build completion (can take up to 1 hour)

Post-Migration Benefits

Over-the-Air Updates

  • Code changes publish instantly without App Store review

  • Update paywalls, features, and content remotely

  • 100% compliant with Apple guidelines

  • Users receive updates when they next open the app

New V3 Features

  • Modular architecture (future-proof)

  • Enhanced native functionalities

  • Support for app clips, widgets, and advanced features

  • Improved build and deployment process

Troubleshooting

Common Issues:

  1. Build Failures: Usually caused by incorrect Bundle ID/App Group linking

  2. Missing Capabilities: Double-check all required capabilities are enabled

  3. Wrong App Group Selection: Ensure each target links to its corresponding group

Getting Help

  • Contact Despia customer support (24/7 availability)

  • Team will help ensure smooth migration

  • Support available for any migration-related questions

Important Notes

  • This is a one-time migration process

  • The new modular structure is designed to be future-proof

  • Android developers don't need to perform these steps

  • Always use exact naming conventions (e.g., "Clip" with capital C)

  • All four targets must be configured even if not all features are used

Summary

While the iOS migration process requires manual configuration, it provides a robust, modular foundation for your application. The benefits include instant over-the-air updates and access to advanced native features. Once completed, you'll have a future-proof setup that won't require similar migrations for new features.

Need Help?

For additional support or questions, please contact our support team at support@despia.com

Updated on
Android Export
Despia OEM