PWA Wrapping Workflow & API Documentation

Workflow Overview

The wrapping process is asynchronous and follows these steps:

1. POST /wrap – Start the wrapping process (returns immediately with a draft ID)
2. GET /draft/{draft_id} – Poll for status updates until completion or failure
3. Download the build – When completed, download the .zip file from download_url

Endpoints

1. Start Wrapping Process

POST /wrapper/wrap

Initiates the PWA wrapping process. Returns immediately with a draft ID for tracking progress.

Request Body

{
  "url": "https://example.com",
  "bundle_id": "com.example.app",
  "team_id": "A1B2C3D4E5",
  "auth_redirects": {
    "accounts.google.com": "https://example.com/auth/google/callback"
  }
}

Request Parameters

Native Authentication vs WebView Authentication

✅ Provide team_id and auth_redirects when:

• You want to handle authentication natively using Universal Links
• Enables device-stored logins (Google, Facebook, etc.)
• More reliable — uses Safari/native browser for authentication

⚠️ Omit team_id and auth_redirects when:

• You want authentication inside the WebView
• Less reliable (some providers block WebView auth)
• Worse UX (no stored logins for social providers)

Example Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "pwa_url": "https://example.com",
  "status": "created",
  "manifest_url": null,
  "project_zip_filename": null,
  "build_zip_filename": null,
  "download_url": null,
  "error_message": null,
  "created_at": "2025-11-10T12:00:00Z",
  "updated_at": "2025-11-10T12:00:00Z"
}

2. Get Draft Status

GET /wrapper/draft/{draft_id}

Poll this endpoint to track wrapping progress.

Path Parameters

Example Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "pwa_url": "https://example.com",
  "status": "completed",
  "manifest_url": "https://example.com/manifest.json",
  "project_zip_filename": "550e8400-e29b-41d4-a716-446655440000.zip",
  "build_zip_filename": "550e8400-e29b-41d4-a716-446655440000.zip",
  "download_url": "https://pwa-ios.aptoide.com/pwa-ios/8.20251013/storage/file/550e8400-e29b-41d4-a716-446655440000.zip",
  "error_message": null,
  "created_at": "2025-11-10T12:00:00Z",
  "updated_at": "2025-11-10T12:05:00Z"
}

Status Flow

Response Fields

Download Contents

When status is completed, the .zip contains:

Always Included

1. Unsigned .app (Simulator) Run directly on iOS Simulator for testing.

2. Unsigned .ipa Requires manual signing before distribution.

3. Xcode Project Folder Use this to manually sign and publish the application.

Included Only With Native Authentication (team_id provided)

4. OAUTH_SETUP.md Instructions for setting up native authentication and Universal Links.

5. apple-app-site-association Preconfigured file to place at: {base_url}/.well-known/apple-app-site-association

⚠️ Not included if native auth is not configured.

Polling Recommendations

Next Steps After Download

✅ With Native Authentication (team_id + auth_redirects)

1. Extract .zip
2. Test in Simulator
3. Read OAUTH_SETUP.md
4. Place apple-app-site-association on your website
5. Open Xcode project & configure code signing
6. Build & archive in Xcode
7. Submit to App Store

⚠️ Without Native Authentication (WebView auth)

1. Extract .zip
2. Test in Simulator
3. Open Xcode project & configure code signing
4. Build & archive in Xcode
5. Submit to App Store

Important Notes

✅ Key Points

• Wrapping runs asynchronously in background
• Build time: 3–8 minutes
• download_url only available when status = completed
• Drafts are kept for historical tracking

⚠️ Important Warnings

• Unsigned .ipa must be signed before distribution

• Native authentication requires:

  • team_id
  • auth_redirects
  • proper hosting of apple-app-site-association

• WebView authentication works but has:

  • worse UX
  • unreliable social login support