# Superapp Docs
> Build, test, and publish native Apple apps with Superapp.
# Welcome to Superapp
Source: https://superapp.dev/docs
Superapp turns plain-language ideas into real native apps for iPhone, iPad, Apple Watch, and Mac. You make the product decisions; Superapp writes the Swift, shapes the interface, and guides your app toward the App Store.
## Getting started
Start a project with one clear outcome. Superapp creates a working first version, then you refine it through conversation. Ask for a screen, change a workflow, connect data, or tune the design in the same direct language you would use with a product team.
## Grow your app
Once your app is live, [Selfdrive](/selfdrive) is the AI marketing agent that grows it every night across Apple Ads, App Store optimization, your website and creator campaigns. You approve the plan; it does the work and emails you every morning.
## What you build
Superapp creates native Swift projects rather than web pages wrapped as mobile apps. The result uses Apple frameworks, can access native device capabilities, and remains a real codebase you can continue evolving.
:::tip
New here? Follow [Build your first app](/build-your-first-app). You can have a useful first version before learning any technical vocabulary.
:::
---
# Account and data controls
Source: https://superapp.dev/docs/account-and-data
Cancelling a subscription, deleting a project, and deleting your account are different actions. Choose the narrowest one that matches what you want to remove.
## Know the difference
Stops future renewals. Your paid access continues through the current billing period, and your Superapp account and projects remain available.
Removes the project from your dashboard. Superapp currently keeps its project data, so this is not the same as permanent account deletion.
Permanently removes the Superapp account and its associated data, signs you out, and cannot be undone. An active subscription is cancelled at the end of its current period.
## Delete a project
1. Open the project menu from the dashboard.
2. Choose **Delete Project**.
3. Type **delete** and confirm.
## Permanently delete your account
1. Open Profile, then open Settings.
2. Choose **Delete Account**.
3. Read the permanent-deletion warning.
4. Type **DELETE** and confirm.
## Before permanent deletion
- Export any Xcode projects, source files, and assets you need to keep.
- Save receipts and invoices needed for accounting.
- Transfer or preserve any backend resources that must continue operating.
- Review connected third-party services and manage them directly with each provider.
:::note
Deleting Superapp does not necessarily delete independently owned Apple, Supabase, RevenueCat, or other third-party accounts and projects. Remove those separately when needed.
:::
If you cannot access the account you need to manage, contact [vitalik@superappp.com](mailto:vitalik@superappp.com) from the account email.
---
# Sign In
Source: https://superapp.dev/docs/accounts-and-sign-in
Add sign-in when the app needs to recognize a person, synchronize their information, or protect private data. For an Apple-platform app, Sign in with Apple usually provides the smoothest production experience.
## Start with Sign in with Apple
Sign in with Apple lets people use an account they already trust instead of creating and remembering another password. It reduces typing, supports Apple’s privacy controls, and feels native on iPhone, iPad, and Mac.
```
Add Sign in with Apple before the private part of the app.
Keep the person signed in between launches. After sign-in, open their dashboard.
Include a sign-out action and an in-app account deletion flow.
```
## Connect identity to app data
Signing in tells the app who the person is. Your backend must use that identity when it reads or writes profiles, projects, uploads, and other private records. Make ownership rules explicit and test them with two different accounts.
- Keep user-owned records private by default.
- Restore the session safely when the app launches again.
- Handle cancellation, connection failures, and expired sessions.
- Provide sign-out and account deletion inside the app.
## Test Apple sign-in on a real device
Treat a physical iPhone or iPad as the reliable test environment for Sign in with Apple. Test the first sign-in, cancellation, relaunch, sign-out, and a second sign-in. Confirm that the correct user data returns after the app restarts.
:::note
A simulator is useful for most interface work, but it should not be the final proof that Apple authentication works. Always complete the sign-in flow on a real device before TestFlight or App Store submission.
:::
## Add a simulator-only skip button
If Apple sign-in blocks day-to-day simulator testing, ask Superapp for a temporary Skip sign-in button. It should create a predictable mock user so you can keep building screens beyond authentication.
```
For simulator development, add a Skip sign-in button that opens the app as a local mock user.
Show it only in debug simulator builds. It must never appear in TestFlight, App Store builds,
or connect the mock user to production data.
```
:::tip
Compile the skip path out of release builds. Hiding the button visually is not enough—the bypass itself must be unavailable in production.
:::
## Email and password sign-in
Traditional email and password authentication is easier to exercise in the simulator and does not depend on the native Apple sign-in sheet. It can be useful when the audience cannot use Apple accounts or the same credentials must work outside Apple platforms.
The tradeoff is a heavier user experience: people must create a password, confirm their email, recover forgotten credentials, and trust another service with account security. Use it when the product requires it, not merely because it is simpler to test.
### Sign in with Apple
_Recommended_
Less typing and a more familiar, private experience. Verify it on a real device.
### Email and password
_Alternative_
Easier to test anywhere, but adds sign-up, recovery, and password-management friction.
## Before release
- Remove every debug authentication bypass from the release build.
- Test with a new account and a returning account on a physical device.
- Verify that signing out prevents access to private screens and cached data.
- Confirm that deleting an account handles its associated data as promised.
:::note
If sign-in is not required for the app’s core value, consider letting people explore first and asking them to sign in only when they save, sync, or share something.
:::
---
# Escape an agent error loop
Source: https://superapp.dev/docs/agent-error-loops
An error loop happens when the agent repeatedly changes code without removing the same underlying failure. More retries usually add noise. Stop, reduce the problem, and ask for evidence before another edit.
## Recognize the loop
- The same compiler or runtime error appears after two attempted fixes.
- The agent alternates between two approaches and reintroduces the previous problem.
- Unrelated files keep changing while the original feature remains broken.
- The explanation says the issue is fixed, but the latest build still fails.
### 1. Stop adding instructions
Let the current run finish. Do not stack new requests while Superapp is still changing files, because each follow-up may start from an incomplete state.
### 2. Name the last known-good state
State which version worked, what single change followed it, and whether the failure is in compilation, launch, behavior, data, or an external service.
### 3. Ask for diagnosis only
Ask Superapp to inspect the first error, trace its cause, and explain the smallest proposed fix before changing code.
### 4. Approve one bounded fix
Protect working screens and project settings explicitly. Build immediately afterward and compare the error with the previous one.
## A recovery prompt
```
Stop making broad changes. The last working version was [identify it]. After [single change], the build began failing with [first exact error]. Diagnose the root cause first. Then make the smallest fix without redesigning screens, changing dependencies, signing, entitlements, bundle identity, or unrelated files. Build again and report whether the original error is gone.
```
## Know when to revert
Revert when two focused attempts leave the same error, the fix changes unrelated architecture, or a previously working core flow is now damaged. Returning to a clean base is often faster than repairing several speculative edits.
:::tip
A different error after a focused fix can be progress. The identical error after the same approach is a signal to stop and change strategy.
:::
---
# App Review and rejections
Source: https://superapp.dev/docs/app-review
A rejection is usually a request for a clearer product, safer behavior, accurate metadata, or better reviewer access. Read the cited guideline and evidence before deciding whether to explain, fix, or appeal.
## Give the reviewer a complete path
- Keep backend services and demo accounts active throughout review.
- Provide a demo account that does not expire or require a private verification code.
- Explain non-obvious gestures, hardware requirements, or location-dependent behavior.
- Describe where subscriptions, account deletion, and restored purchases can be tested.
- Make contact information accurate so Apple can reach you quickly.
## Common preventable rejection reasons
- Crashes, broken links, unfinished screens, or an incomplete primary journey.
- The reviewer cannot sign in or reach an important feature.
- Metadata and screenshots promise behavior missing from the submitted build.
- The app collects data or requests permissions without a clear, necessary purpose.
- Account creation exists without in-app account deletion.
- Digital purchases bypass Apple's required purchase system.
- The app provides too little lasting functionality or feels like a thin website wrapper.
- User-generated content lacks reporting, blocking, moderation, or contact mechanisms.
## How to respond
### 1. Read the complete message
Identify the guideline, the reviewer's steps, affected device, and whether Apple asks for information or a new binary.
### 2. Reproduce the issue
Test the same build and account through TestFlight. Do not assume the problem is limited to Apple's environment.
### 3. Choose explanation or correction
If the feature already complies, reply with short numbered steps and supporting context. If it does not, fix the app or metadata and state exactly what changed.
### 4. Reply and resubmit
Use the App Review conversation in App Store Connect. Be factual and respectful; do not create a new app record or submit unchanged builds repeatedly.
:::note
If you believe Apple applied a guideline incorrectly after a clear response, use Apple's appeal process. Approval is always Apple's decision, and review rules can change.
:::
Review the current [App Review Guidelines](https://developer.apple.com/app-store/review/guidelines/) before every major release.
---
# App Store submission checklist
Source: https://superapp.dev/docs/app-store-checklist
Treat the submitted build as a finished product, not a prototype. This checklist catches the issues most likely to block testing or make the listing disagree with the app.
## App quality
- Test first launch, the main journey, relaunch, offline behavior, and failure states.
- Remove placeholder content, unfinished buttons, debug screens, and sample accounts.
- Test on at least one real device with the release configuration.
- Confirm every permission is requested only when its feature is used.
- Check readable text, VoiceOver labels, Dynamic Type, dark mode, and keyboard behavior.
## Accounts and reviewer access
- If people can create an account, include account deletion inside the app.
- Do not require sign-in unless the core experience genuinely needs an account.
- Test Sign in with Apple on a physical device.
- Provide a working demo account when review cannot reach the main experience otherwise.
- Put any unusual testing steps, hardware needs, or sample data in Review Notes.
## Product page
- Use the final app name, icon, subtitle, category, description, and keywords.
- Show the current interface in screenshots; never advertise absent functionality.
- Use public privacy and support URLs that open without an account.
- Choose pricing and availability intentionally.
- Complete the age-rating, content-rights, and export-compliance questions accurately.
## Privacy and payments
- Make App Privacy answers match the code, SDKs, analytics, and privacy policy.
- Publish the App Privacy answers in App Store Connect before submission.
- Explain subscription price, billing period, and trial terms before purchase.
- Include Restore Purchases and test it with a sandbox account.
- Submit new in-app purchases or subscriptions for review when required.
## Final build
- Confirm the bundle identifier belongs to this App Store Connect record.
- Use a new version when the previous marketing version is locked.
- Wait for Apple to finish processing the exact uploaded build.
- Install that build through TestFlight and complete one final smoke test.
- Read every field once more before selecting Submit for Review.
:::tip
A reviewer should be able to open the app, sign in when necessary, and reach its main value without guessing. If a step is not obvious, explain it in Review Notes.
:::
---
# Screenshots and product page
Source: https://superapp.dev/docs/app-store-listing
The App Store product page should make one promise, demonstrate it visually, and match the exact build Apple reviews.
## Complete the listing in Superapp
Superapp can use AI to draft listing information from your code. Review every sentence: generated copy is a starting point, and you are responsible for its accuracy.
- **Description:** explain the primary benefit, main features, and intended user in up to 4,000 characters.
- **Subtitle:** summarize the value in no more than 30 characters.
- **Keywords:** use relevant comma-separated terms within the 100-character limit without repeating the app name.
- **Category:** choose the category that best represents the main function.
- **Promotional text:** highlight timely information in up to 170 characters; it can be changed without a new build.
## Build a screenshot story
Apple accepts one to ten screenshots per supported device presentation. The first screens matter most: show the strongest result before secondary settings or onboarding.
### 1. Choose the story
Lead with the primary outcome, then show the short path that creates it. Give each image one clear message instead of filling it with feature lists.
### 2. Capture the real build
Use realistic, safe sample data and the current interface. Avoid personal information, debug overlays, device notifications, or features that are not yet available.
### 3. Add restrained framing
Short headlines and branded backgrounds can improve comprehension, but the app itself should remain legible. Do not obscure important controls or imply a result the app cannot produce.
### 4. Upload and inspect
Add the assets in Superapp's screenshot step, check their order, and review the product page in App Store Connect. Provide iPad assets when the app supports iPad.
:::note
Apple's accepted dimensions change as devices evolve. Use the current [screenshot specifications](https://developer.apple.com/help/app-store-connect/reference/app-information/screenshot-specifications/) rather than resizing from an old template. Screenshots cannot contain transparency.
:::
## Information for App Review
Reviewer contact details and notes are not marketing copy. Provide a reachable person, complete instructions, a demo username and password when required, and any context needed to activate hardware, location, subscription, or account-dependent features.
---
# Generate your app website
Source: https://superapp.dev/docs/app-website
Superapp can build a public website alongside your native app. It becomes the place where people learn about the app, find support, read its privacy policy, and follow the App Store link.
:::tip
Website generation is available in Superapp on the web today. It is coming to the Desktop app soon.
:::
## One project, two products
The website lives in the same Superapp project as your iOS app, but it is a separate web experience—not a wrapper around the app. Superapp reads the finished product and uses its name, icon, features, and visual direction to create a matching marketing site.
Your native app remains native Swift. The website gives it a public home that works in any browser and provides the URLs Apple expects during App Store submission.
## How to generate it
### 1. Finish the app's core experience
Build enough of the app that its purpose, main features, name, and visual style are clear. The website is more accurate when Superapp has a real product to describe.
### 2. Ask for a website
In Superapp on the web, ask the agent to create a website for the app. You can also choose **Generate a website** during the publishing flow when Superapp asks for privacy and support URLs.
### 3. Review the private preview
Superapp builds the site and gives you a draft preview. Check the feature descriptions, app icon, contact details, privacy language, and every link before making it public.
### 4. Publish when it is ready
Publishing moves the approved draft to the live website. You can continue improving the site later, preview the next version privately, and publish again when you are satisfied.
## What Superapp includes
- **A marketing homepage** based on the app's real purpose and features.
- **Your app identity**, including its name, icon, and a visual style that belongs with the native product.
- **An App Store call to action** using the live listing link when one is available, or a clear coming-soon state before launch.
- **A privacy page** drafted from the data, accounts, permissions, and services the app actually uses.
- **A support page** with a contact method for users and App Store review.
## Edit the website with prompts
Treat the website like the app: describe the outcome you want. Ask Superapp to rewrite a headline, reorder features, change the visual tone, add a launch announcement, or update the App Store link. Changes go to the draft first, so the public version stays unchanged until you publish.
```
Update the website to match the latest version of my app.
Make the opening section explain the main benefit in one sentence,
show the three strongest features, and keep the design minimal.
Do not change the privacy or support contact details.
```
## Before you publish
- Replace placeholder contact information and confirm the support inbox is monitored.
- Make sure the privacy policy matches the current app, not an earlier build.
- Open every public page while signed out to confirm that Apple can access it.
- Use the real App Store URL after the listing becomes available.
- Check the website on both a phone and a desktop browser.
:::note
The generated website is a companion to your app. It is not the app itself and does not turn the native Swift project into a web app.
:::
---
# Create your Apple Developer account
Source: https://superapp.dev/docs/apple-developer-account
You can build and test before joining, but publishing to the App Store requires an active Apple Developer Program membership. Create it early: identity or organization checks can take time.
## Choose individual or organization
### Individual
Best for a solo developer or sole proprietor. Your verified personal legal name is shown as the seller on the App Store.
### Organization
Best when a registered legal entity should appear as the seller. Apple verifies the entity and that the enrollee has authority to bind it.
:::note
The membership type affects the public seller name. Do not enroll as an individual if the company name must appear on the product page.
:::
## Prepare before enrolling
- An Apple Account with two-factor authentication enabled.
- Accurate legal name, address, phone number, and trusted devices.
- A government-issued photo ID when Apple requests identity verification.
- For an organization, its legal entity details and an authorized representative.
- A payment method for the annual membership fee shown in your region.
### 1. Start enrollment
Enroll through the Apple Developer website or the Apple Developer app. Use the Apple Account that should control publishing for the long term.
### 2. Verify the identity
Enter legal information exactly as it appears on official records and complete any identity or organization verification Apple requests.
### 3. Accept agreements and pay
Accept the current program agreement and complete the membership purchase. Enrollment is ready only after Apple confirms the membership is active.
### 4. Connect the account in Superapp
Open **Publish**, sign in with Apple, complete verification, and select the team that should own the app. Keep the Account Holder available when Apple requires a new agreement.
## Avoid account problems
- Do not share Apple Account passwords between teammates.
- Keep trusted phone numbers and recovery information current.
- Accept new Apple agreements before attempting another submission.
- Renew the membership before it expires.
- Confirm the selected team before Superapp creates the app record.
See Apple's current [enrollment requirements](https://developer.apple.com/programs/enroll/) before applying.
---
# Assets and media
Source: https://superapp.dev/docs/assets-and-media
Good source material gives Superapp a visual language to work from. Add intentional assets early when photography, illustration, or brand identity is central to the experience.
## Prepare useful assets
- Use SVG or PDF vectors for simple marks and interface artwork.
- Use high-resolution PNG or JPEG files for raster images.
- Name files by purpose, not by export number.
- Confirm that you have permission to ship every asset.
## Give visual references
Explain what to borrow from a reference: density, color mood, hierarchy, motion, or navigation. Superapp should translate those qualities into your product rather than copy another app’s brand or interface.
:::note
Keep the app icon simple, legible at small sizes, and free of transparency. Apple applies the final corner mask.
:::
---
# Do you need a backend?
Source: https://superapp.dev/docs/backend
A backend is the part of an app that runs away from the device. It can identify users, store shared information, synchronize changes, protect private operations, and receive events from other services. Many useful apps can launch without one.
## Keep the app local when one device is enough
Local storage is often the simplest and most private choice when information belongs to one device and never needs to be shared. The app can still preserve data between launches without creating accounts or running cloud infrastructure.
- Calculators, timers, converters, and focused offline utilities.
- Personal checklists, logs, or journals without cross-device sync.
- Small games and creative tools whose state stays on the device.
- API-powered tools that display a result without storing user history.
:::tip
Ask Superapp to store important local data persistently and verify that it survives a full app restart. Use the Keychain for sensitive device-only values.
:::
## Use a backend when data crosses a boundary
A backend becomes necessary when the app must recognize the same person elsewhere, allow several people to interact, or enforce a rule that users must not be able to bypass.
- **Accounts:** profiles, sign-in, recovery, and user-owned records.
- **Synchronization:** the same information on iPhone, iPad, and Mac.
- **Shared experiences:** teams, comments, messaging, feeds, or multiplayer.
- **Cloud files:** photos, audio, documents, or uploads available elsewhere.
- **Protected logic:** private API keys, webhooks, moderation, and rate limits.
## Start local and add cloud features later
Some products sit between the two choices. A journal can begin entirely on-device and add backup later. An AI tool can keep short-term context locally, then introduce accounts when people ask for history across devices. Build around the current promise rather than future possibilities.
## Choose your Superapp backend path
### Superapp Cloud
_Web default_
The managed option and the environment where Superapp's AI works best. Its closed, known system lets the AI manage backend changes with fewer unknowns.
### Self-hosted Supabase
_Mac option_
Superapp for Mac can connect to Supabase infrastructure you operate when ownership and deployment control matter more than managed setup.
## Choose the backend early
The cleanest time to choose self-hosted Supabase is when starting a project on Superapp for Mac. Once an app already uses Superapp Cloud, moving it is a migration—not a settings toggle. The database schema, existing records, authentication, storage, server-side functions, and app configuration may all need to move together.
:::note
Moving an already-created project from Superapp Cloud to self-hosted Supabase is completed on request. Email [vitalik@superappp.com](mailto:vitalik@superappp.com) and the team will help plan the migration. Do not replace backend URLs or keys manually.
:::
If you are building on the web, continue with [Superapp Cloud](/superapp-cloud). On Mac, you can also follow [Connect Supabase](/connect-supabase) to use your own self-hosted project.
---
# Fix Swift and Xcode build errors
Source: https://superapp.dev/docs/build-errors
Xcode often prints many messages after one root failure. Start with the earliest specific error that names a file, symbol, package, or build setting. Later failures may disappear automatically when that first cause is fixed.
## Capture useful evidence
- The complete first error, including its filename and line when shown.
- The target, scheme, device, and operating-system version being built.
- The last prompt or manual change before the build stopped working.
- Whether the same version builds for Simulator, a real device, or neither.
## Common categories
Check spelling, target membership, imports, file creation, and package availability. Fix the missing dependency or declaration before editing every call site.
Use the exact file and line from the first diagnostic. Ask for the smallest type-correct change, then rebuild before refactoring nearby code.
Confirm the network connection and package version. Avoid deleting lockfiles or changing dependency versions unless the diagnostic points to the dependency graph.
Treat signing, architecture, capabilities, and device-only frameworks as likely causes. Continue with the signing and entitlements guide.
## Use one-error-at-a-time repair
1. Build once and preserve the full diagnostic.
2. Select the first actionable error.
3. Ask Superapp to explain why it occurs in the current code.
4. Apply one bounded fix and rebuild.
5. Continue only if the first error disappears or materially changes.
:::note
“Build succeeded” is the proof. A confident explanation without a successful latest build is not a completed repair.
:::
---
# Build your first app
Source: https://superapp.dev/docs/build-your-first-app
The fastest way to learn Superapp is to build something small enough to test immediately. Start with one person, one problem, and one main action.
### 1. Start a project
Open Superapp on the web or Mac and describe the app you want. A useful first prompt names the user, the core job, and the two or three screens needed to complete it.
### 2. Let Superapp build
Superapp plans the first version and generates the native interface and behavior. Keep the project open while the first build completes.
### 3. Try the main flow
Use the preview like a real user. Tap every primary action and note anything confusing, missing, or slower than it should be.
### 4. Improve one thing at a time
Send a short follow-up such as “Make saved workouts editable” or “Use a warmer, quieter visual style.” Small, testable requests make iteration fast and predictable.
## A strong starter prompt
```
Build a native iPhone app for runners who want to plan interval workouts.
Include a simple home screen, a workout builder, and a run history.
Keep the interface dark, focused, and easy to use with one hand.
```
:::tip
Build the smallest complete loop first. Accounts, subscriptions, notifications, and advanced settings are easier to add once the core experience feels right.
:::
---
# Connect an API
Source: https://superapp.dev/docs/connect-an-api
An API lets your app request data or trigger actions in another service. Before connecting one, confirm that the provider permits your use case and offers the data you need.
### 1. Define the user action
State what the person does, what is sent, and what the app should show in return.
### 2. Share the official documentation
Give Superapp the provider’s current API documentation, required endpoints, and an example response. Do not paste a private key into the prompt.
### 3. Handle every state
Design loading, empty, offline, rate-limit, permission, and error states—not only the successful response.
### 4. Test with safe data
Use a sandbox or development account before connecting production users and records.
---
# Connect Supabase
Source: https://superapp.dev/docs/connect-supabase
Bring your own Supabase project when you need direct control of the backend, already have data there, or want to manage infrastructure in your own account. This option is available in Superapp for Mac.
:::note
Superapp's AI works best with Superapp Cloud because it is a closed, known system. In a self-hosted environment, custom policies, extensions, versions, functions, and manual changes can affect what the AI can safely understand and manage.
:::
## First identify your situation
### Connect it directly
_New Mac project_
Choose the Supabase project you control, connect it through Superapp, and define the data and access model before inviting users.
### Request a migration
_Existing Superapp Cloud project_
Contact the Superapp team. Existing cloud data and services must be moved as a coordinated migration rather than by changing a URL or key.
### 1. Create or choose a Supabase project
Use a separate project for production. Keep development data isolated while the app changes quickly.
### 2. Connect it in Superapp
Provide the project details through Superapp’s secure connection flow. Never paste service-role secrets into app code or chat.
### 3. Describe access rules
Explain who owns each record and who may read, create, update, or delete it. Verify those rules before adding real users.
### 4. Test the complete backend flow
Create two test accounts and verify sign-in, record ownership, uploads, synchronization, and permission failures before using production data.
:::note
Public app keys are different from server secrets. If you are unsure which credential a field expects, stop and confirm before sharing it.
:::
## Already using Superapp Cloud?
Do not reconnect the app manually. Email [vitalik@superappp.com](mailto:vitalik@superappp.com) with your Superapp account email and project name to request a move to self-hosted Supabase. The team will review the project and coordinate the appropriate migration path.
---
# Connect your app
Source: https://superapp.dev/docs/connect-your-app-to-selfdrive
Selfdrive works on one app at a time, in its own workspace. You can connect as many apps as you like and switch between them.
## Three ways to connect
### Paste an App Store link
On the Selfdrive page, paste the public App Store link of your app. The agent reads the public listing, reviews and category right away and starts preparing your growth plan. This is the fastest way to see what Selfdrive would do before giving it any access.
### Pick an app you built in Superapp
Choose **Connect app from Superapp** and pick a project. The app must already be live on the App Store. Selfdrive reuses what it knows about the project, including its website if you generated one.
### Sign in with your Apple Developer account
Choose **Connect with App Store Connect**. Sign in with the Apple ID that publishes the app, or paste an App Store Connect API key instead, then pick the app from the list. Use the account and team that own the app; a different team cannot see it.
:::note
The growth plan is prepared in the background. Until it is ready, tasks cannot be approved yet and the dashboard says research is still being prepared.
:::
## What the agent uses Apple access for
Connecting App Store Connect lets the agent:
- read your app's analytics, such as impressions, product page views and downloads, so proposals and the daily report use your real numbers;
- read your current listing metadata, so listing changes are drafted against the version Apple will accept;
- submit the listing changes and version submissions you approve.
Without App Store Connect, the agent still works from public data: your public listing, keyword ranks, reviews and competitors. Sections that need owned data are marked unavailable.
Apple Ads is a separate connection. See [Apple Ads](/selfdrive-apple-ads).
## Your data and security
- **Your password is never stored.** Signing in creates an Apple session that Selfdrive keeps encrypted, or you provide an API key you can revoke in App Store Connect.
- **Analytics are stored for your agent.** The nightly run and the daily report read them. They are used for your workspace only.
- **You keep ownership.** Nothing about the app's ownership, team or pricing changes. Revoke the API key or session on Apple's side at any time, and disconnect Apple Ads from the Apple Ads tab.
## When you are ready to run tasks
Getting the growth plan is free. Approving tasks needs the **Max** plan. When you approve your first task without Max, Superapp asks you to upgrade; your workspace and plan stay where they are.
## Removing an app
Open the app menu in the workspace and delete it. If a creator campaign is still running, stop it first in chat and wait for the confirmation; remaining payouts are settled through Viral before the app can be removed.
---
# Work with creators
Source: https://superapp.dev/docs/creator-partnerships
A creator partnership works when audience fit, product relevance, and creative trust align. Follower count alone says little about whether viewers will understand or use your app.
## Build a qualified creator list
Search the questions, routines, and communities surrounding the problem. Review recent posts across platforms and record typical views, meaningful comments, posting consistency, audience location, format, and previous sponsorships.
- Their audience closely matches the app’s first users.
- Comments show conversation rather than repetitive or generic reactions.
- The creator has a recognizable format the app can enter naturally.
- Past sponsored content is transparent and still useful to the audience.
## Send specific outreach
```
Hi [name] — I build [app], which helps [audience] achieve [result].
Your recent [specific series/post] reaches exactly that situation.
Are you open to a paid collaboration? I can send a short brief and working TestFlight build.
```
Keep the first message short, identify why the creator fits, and state that the opportunity is paid. Give them a real build before asking them to endorse it.
## Put the agreement in writing
- Deliverables, platforms, dates, format, and revision limits.
- Flat fee, performance component, payment schedule, and expense handling.
- Tracking link, reporting window, and success metrics.
- Usage rights, paid amplification, whitelisting, territory, and duration.
- Required sponsorship disclosures and prohibited product claims.
- Cancellation, missed deadlines, and content-removal terms.
## Evaluate beyond views
Compare total spend with attributed installs, trials, purchases, and retained users. Save strong hooks and audience insights even when a partnership is not profitable; the creative learning can improve organic posts and paid ads.
:::note
Paid relationships and free products generally require clear disclosure. The disclosure should be easy to notice with the endorsement itself; confirm the rules that apply in every market where the campaign runs.
:::
---
# Buy credit top-ups
Source: https://superapp.dev/docs/credit-top-ups
Top-ups are one-time credit purchases for eligible paid accounts. They carry across billing cycles and are valid for twelve months from purchase.
## Who can buy a top-up
The account must have an active paid subscription, or a cancelled subscription that is still inside its paid period. Free, expired, incomplete, trialing, and payment-overdue accounts cannot purchase a top-up.
### 1. Open Profile
Find your credit balance and choose the option to buy credits.
### 2. Choose a pack
Select the amount that covers the near-term work. The checkout shows the one-time price before payment.
### 3. Complete Stripe checkout
Confirm payment through the secure checkout, then return to Profile. A success message shows how many credits were added.
### 4. Verify the balance
The top-up appears separately in the balance breakdown even though the main number shows one combined usable total.
## How top-up credits are used
Superapp spends daily free, promotional, and subscription credits before top-up credits. This protects the longer-lived purchased balance. The expiration date is shown while a top-up balance remains.
:::note
A top-up does not start, renew, or extend a subscription. It only adds credits to the account that purchased it.
:::
---
# How credits work
Source: https://superapp.dev/docs/credits
Credits measure the work Superapp performs for you. They are usage-based: a quick, targeted edit usually costs less than a request that explores a large project, reasons through a complex feature, generates substantial code, and verifies the result.
:::tip
One message does not automatically cost one credit. You pay for the work completed during the run, and the balance can move by fractions of a credit.
:::
## Two kinds of work use your balance
### Agent usage
_While building_
Planning, reading project context, reasoning, writing code, and using tools such as search or media generation.
### Superapp Cloud usage
_After connecting Cloud_
The infrastructure your app consumes, including compute, database and file storage, data transfer, functions, and realtime messages.
Both are shown in credits and deducted from your Superapp balance. Cloud usage is also broken down by project so you can see which app and resource created the cost.
## How building credits are calculated
Superapp records the actual AI usage for each step, applies the rate for the selected model, and converts that provider cost into credits. The current calculation is:
```
building credits = underlying model and tool cost × 3
```
The total can change from one request to another because it includes:
- **Model:** Smart is suited to everyday work; more capable modes generally use credits faster.
- **Context:** reading more project files or a longer conversation requires more input.
- **Output:** a broad feature usually needs more reasoning and generated code than a focused adjustment.
- **Tools:** searches, transcription, image work, screenshots, and other metered operations add their own usage.
- **Verification:** multi-step work may spend credits while checking and correcting the result.
:::note
Cached project context costs less than reading the same information as new context. This is one reason two similarly sized prompts can still have different totals.
:::
## What different requests usually mean
Usually a fraction of a credit when the target is clear and Superapp only needs to inspect and modify a small part of the project.
Often costs more because Superapp must understand neighboring code, make several coordinated edits, and verify the full interaction. A substantial screen can be around one credit, but the actual total depends on the work performed.
Can cost several credits when it involves deeper exploration, repeated tool calls, complex reasoning, multiple fixes, or a higher-capability model.
If no AI or tool work starts, there is no usage to record. If Superapp has already performed part of the work, that completed usage can still consume credits even when the final result fails or you stop the run.
## Search and other metered tools
Web search is charged separately at **0.03 credits per search request**. A single task can make more than one search. Voice transcription, images, icons, and other generated media are metered according to the service used, so they do not all have the same cost.
## How Superapp Cloud credits are calculated
Cloud usage is measured from the resources your connected project actually consumes. Superapp converts the infrastructure cost into credits with this calculation:
```
cloud credits = underlying infrastructure cost × 4
```
- **Compute:** time the cloud project is actively running.
- **Database storage:** information retained in database tables.
- **File storage:** photos, audio, documents, and other stored objects.
- **Data transfer:** information sent out from the project.
- **Functions and realtime:** backend function calls and live messages.
Open the Cloud usage view for a project to see its category breakdown. Recent Cloud activity can take up to an hour to appear, so the chart may briefly trail the balance.
## How your available balance is used
The credit number in Superapp combines the active credit sources on your account. When usage is recorded, Superapp applies them in this order:
1. Free credits
2. Promotional credits
3. Credits included with the current subscription
4. Purchased top-up credits
Using the shortest-lived credits first protects the more flexible balance. Promotional and top-up credits show an expiration date when one applies. Purchased top-ups carry across billing cycles and are currently valid for twelve months.
## Resets, renewals, and top-ups
- Superapp provides free credits to start in most countries; in some regions the free plan is not available. Unused free credits expire at midnight UTC and do not carry over.
- Subscription credits refresh with the billing period. The new allowance replaces the remaining subscription allowance rather than adding to it.
- Eligible paid accounts can buy a one-time top-up without moving to a larger monthly plan.
- Promo and top-up balances remain separate internally even though the main credit number shows one usable total.
## Make credits go further
- Name the exact screen, behavior, and expected result.
- Use Smart for routine work and move up only when the task needs deeper reasoning.
- Group one coherent change together instead of sending many tiny follow-ups.
- Split very broad redesigns into testable milestones before implementation.
- Attach only the files and references that matter to the current request.
- Check Cloud usage by project when the balance changes between building sessions.
:::note
Rates and included allowances can change as models and infrastructure evolve. Your current in-product balance, plan page, and project usage view are the source of truth.
:::
---
# Expo vs. Swift
Source: https://superapp.dev/docs/expo-vs-swift
Superapp was conceived as the first AI app builder built natively around Swift. Its originality comes from rejecting the usual web or React Native foundation—not from adding a Swift export later.
:::tip
Superapp began with a strong belief: agents build better Apple apps when they work directly with Swift, SwiftUI, Xcode, and Apple's compiler. Swift is the product, not an export format.
:::
## The short version
### Expo and React Native
One JavaScript or TypeScript codebase can serve iOS and Android. This is a practical choice when cross-platform reach matters most and the app uses familiar mobile patterns.
### Swift and SwiftUI
The app speaks Apple's language directly. It uses native frameworks, compiles with Apple's toolchain, and can take advantage of the platform without a cross-platform compatibility layer.
## Why agents struggle with React Native
React Native is capable technology, but an agent has to coordinate more moving parts: a JavaScript runtime, React Native and Expo versions, native modules, configuration plugins, package dependencies, permissions, and the iOS or Android build underneath them. A change that looks correct in TypeScript can still fail when the native project compiles or runs on a device.
Package knowledge also ages quickly. A library example may target a different Expo SDK, depend on an abandoned native module, or behave differently after a platform update. Each extra layer gives an agent another place to make a plausible but incompatible choice.
## Why Superapp chose Swift
- **One source of truth.** The code, compiler errors, simulator, device, and App Store build all belong to the same Apple toolchain.
- **Direct feedback.** Swift's type system and compiler give the agent precise problems to fix instead of hiding them behind several abstraction layers.
- **Native by default.** SwiftUI, HealthKit, WidgetKit, ActivityKit, StoreKit, ARKit, Apple Watch, and other Apple frameworks are available without waiting for a cross-platform wrapper.
- **A higher ceiling.** Native navigation, accessibility, animation, background work, and device integrations can follow Apple's platform conventions.
- **Your real project.** Superapp produces a standard Swift project you own and can continue in Xcode with no rewrite or migration step.
## When Swift is the superior choice
Swift is not universally better for every product. It is the superior choice when the destination is the Apple ecosystem and quality on Apple devices matters more than sharing one codebase with Android. That includes apps built around widgets, Live Activities, HealthKit, Apple Watch, advanced camera or audio work, augmented reality, or a deeply native interface.
## When Expo may be the better choice
Choose Expo or another cross-platform stack when launching on iOS and Android together is a core requirement, your team already works in React, or the product mainly consists of standard feeds, forms, dashboards, and messaging. Shared reach is a real advantage; it is simply a different priority from Superapp's Apple-first approach.
## What Superapp builds
Superapp's agent writes native Swift and SwiftUI, compiles against Apple's SDKs, reads compiler errors, and repairs the project in the same environment used to ship it. On the web, Superapp runs that toolchain in the cloud. On Mac, you can build locally and open the generated project in Xcode whenever you want deeper control.
:::note
Superapp is deliberately Apple-first. If Android is essential to your product, choose a cross-platform builder. If you want the best possible Apple app, Superapp is built for that decision from the first prompt.
:::
---
# Figma to native SwiftUI
Source: https://superapp.dev/docs/figma-to-swiftui
Superapp uses your Figma screens as a visual reference and rebuilds them as original SwiftUI. The result is a working native project, not exported web code or a clickable prototype.
:::note
Figma is the design source, not the behavior specification. Explain navigation, data, validation, loading, errors, and device features that cannot be seen in a static frame.
:::
### 1. Prepare the frames
Choose the screens that define the primary journey. Name frames and layers clearly, use consistent components, and include important states such as empty, loading, error, and success.
### 2. Connect Figma
Select the Figma option in Superapp, sign in to connect your account, and paste links to the relevant screens or frames. You can reference multiple screens in the same build.
### 3. Describe how it behaves
Tell Superapp which screen opens first, what every important action does, where data comes from, and which native capabilities the app needs.
### 4. Build and compare
Generate the SwiftUI app, then compare it with the source at the same device size. Fix layout hierarchy and interaction first; tune spacing, typography, and animation after the full journey works.
## Example prompt
```
Use the connected Figma onboarding, dashboard, and detail screens as references.
Build them as native SwiftUI. Preserve the visual hierarchy and component style.
The dashboard loads the signed-in user's records from Supabase.
Add loading, empty, offline, and error states that are not shown in Figma.
```
## Before you finish
- Replace rasterized text and fake controls with native SwiftUI components.
- Test Dynamic Type, dark mode, keyboard avoidance, and VoiceOver.
- Confirm every linked screen has a real route and a way back.
- Use licensed fonts, icons, photos, and illustrations.
- Test the result on a real device rather than judging only from screenshots.
---
# Choose a growth channel
Source: https://superapp.dev/docs/growth-channels
The best channel is the one that repeatedly reaches people with the problem your app solves. Start with one or two channels you can operate well, then expand after the economics and creative process are understood.
## 1\. Product-led organic content
Demonstrations, tutorials, progress stories, and before-and-after posts are inexpensive to test and teach you which language earns attention. They require consistent production and can fluctuate sharply from post to post.
## 2\. Founder-led content
Explain the problem, show decisions, respond to feedback, and document real customer outcomes. This builds trust and produces direct qualitative learning, but depends on the founder’s willingness to publish regularly.
## 3\. Creator partnerships
Pay established creators to place the app inside formats their audience already values. Prioritize audience fit and retained conversions over followers or isolated viral posts.
## 4\. Dedicated user-generated creative
Commission creators to produce a steady library of original assets for brand accounts and ads. Begin with a small test group, find a repeatable concept, then expand production.
## 5\. Paid acquisition
Paid social and search can provide controllable volume once a message and conversion path work organically. Set a test budget, attribution method, stopping rule, and target customer economics before launch.
## 6\. Communities and useful participation
Answer questions, share expertise, and invite relevant people to a beta where communities already discuss the problem. Follow each community’s promotion rules and avoid disguised advertising or coordinated manipulation.
## 7\. Product and distribution partnerships
Work with coaches, schools, clubs, publishers, employers, or complementary products that already serve the audience. Define the shared value, ownership of the customer relationship, support duties, attribution, and commercial terms before integrating.
## Compare channels with one scorecard
- Qualified reach and App Store page visits.
- Cost per download, activated user, trial, and paying customer.
- Seven- and thirty-day retention by acquisition source.
- Refunds, support burden, and contribution after variable costs.
- Time required to produce, approve, and refresh creative.
:::note
Do not scale from one unusually strong result. Repeat the campaign, verify attribution, and confirm that acquired users retain before committing a larger budget.
:::
---
# Build a repeatable growth loop
Source: https://superapp.dev/docs/growth-playbook
Growth is a loop: reach the right people, help them experience value, retain them, and use what you learn to improve the next acquisition cycle. Scale only after the loop works at a small volume.
## Instrument the complete journey
```
impression → App Store view → download → onboarding → activation
→ trial or purchase → retained use → referral or renewal
```
Give every stage one primary metric. Diagnose from the top: if qualified people never reach the product page, onboarding changes cannot solve the immediate problem.
## Grow in stages
### 1. Prove the promise
Interview and recruit users directly. Confirm that they reach and repeat the core result.
### 2. Find one acquisition signal
Publish original content, work with a small creator, or join a relevant community. Look for one message and audience combination that produces activated users.
### 3. Make the result repeatable
Reproduce the winning concept several times. Document its audience, hook, format, conversion path, and cost before increasing volume.
### 4. Scale with guardrails
Increase spend or output gradually while monitoring acquisition cost, trial conversion, retention, refunds, support volume, and proceeds after platform fees.
## Know the unit economics
Compare the cost to acquire a paying customer with the contribution that customer produces after refunds, fees, creator payments, and variable service costs. Use conservative retention assumptions; early revenue alone can hide an unprofitable channel.
## Run a weekly growth review
- Which audience and message produced the most activated users?
- Where did the largest qualified-user drop occur?
- Which cohort retained or converted better after seven and thirty days?
- What single experiment will reduce the largest uncertainty next week?
:::tip
A revenue target is an outcome, not a plan. Build the plan from acquisition volume, conversion, retention, price, and cost assumptions you can measure separately.
:::
---
# History and recovery
Source: https://superapp.dev/docs/history-and-recovery
Superapp keeps a history of previous project versions. When a change breaks the app or takes it in the wrong direction, you can revert to a known-good version instead of adding increasingly complicated repair prompts.
## Use a safe iteration loop
1. Start from a version whose main flow works.
2. Request one coherent change and wait for it to finish.
3. Test the affected flow and nearby screens.
4. Keep the result or return to the last good version before continuing.
## When reverting is the safer choice
- The same error remains after two focused repair attempts.
- A narrow feature request unexpectedly changed several working areas.
- Signing, entitlements, dependencies, or project structure changed without intent.
- The current state is harder to explain than the original requested change.
- You need a reliable build immediately for testing or release.
## Revert in Superapp
### 1. Wait for the agent
Let the current change finish. Superapp disables restoration while the agent is still working so project state cannot change underneath it.
### 2. Open edit history
Open the project's edit history and find the last version whose app behavior and build result you recognize as correct.
### 3. Choose Revert
Review the selected version's message and time, then confirm. Superapp restores the project and automatically attempts a new build.
### 4. Verify the restored app
A successful revert message confirms restoration. If the files restore but the rebuild fails, treat the new build diagnostic separately before continuing.
:::note
Restoring an earlier version changes the project, not external systems. Database records, App Store Connect configuration, RevenueCat products, Supabase changes, and other remote state may need separate recovery.
:::
## Recover a Mac project
When working locally or with Claude Code, Codex, or Xcode, create small version-control commits at meaningful checkpoints. Review the diff before restoring anything, preserve uncommitted work that matters, and revert only the external changes responsible for the failure.
## Continue from a clean base
After restoration, reproduce the original feature request as a smaller task. Name the working behavior that must remain unchanged and verify the next build before continuing.
---
# Bring assets and design references
Source: https://superapp.dev/docs/import-design-assets
Good migration inputs explain both what the old product looks like and why it behaves that way. Bring the smallest reliable set of references needed to rebuild the experience.
## What to bring
- Final logo and app icon artwork with the right to use it.
- Original photos, illustrations, audio, video, and licensed fonts.
- Figma frames or screenshots for important screens and states.
- Brand colors, typography rules, spacing, and reusable component behavior.
- Copy, validation messages, onboarding text, and notification language.
- A short description of every reference and where it belongs.
## Reference or in-app asset?
### Visual reference
A screenshot or mockup shows composition and style. Superapp should interpret it and rebuild the interface from native SwiftUI components.
### Production asset
A logo, photo, illustration, sound, or video should appear as the original file inside the app. Say explicitly that it must be saved and used verbatim.
## Organize the handoff
Use descriptive filenames, remove outdated alternatives, and provide one approved version of each brand asset. When several screenshots describe a flow, number them in interaction order and explain what changes between them.
:::note
Remove customer names, email addresses, tokens, private URLs, and production records from every screenshot and attachment before sending it to Superapp.
:::
---
# Invoices, receipts, and refunds
Source: https://superapp.dev/docs/invoices-and-refunds
Stripe securely processes Superapp payments. Keep the receipt or invoice ID for every subscription and top-up purchase—it is the quickest way to trace a charge.
## Find a receipt or invoice
- Check the inbox and spam folder for the email used at Stripe checkout.
- From Superapp Profile, choose **Change payment method** (or **Billing history** after a subscription has ended) to open the Stripe billing portal and view available billing documents.
- If a document is missing, contact support with the account email, charge date, and amount.
## Company and tax details
Add or update the legal name, billing address, and tax details in the Stripe billing portal before the next invoice is issued. Previously issued documents may not be editable, so contact support if a historical invoice needs review.
## Refund policy
Superapp fees are non-refundable except where required by law. The current policy is in the [Superapp Terms of Service](https://superapp.dev/terms). If a charge is duplicated or incorrect, report it promptly so the team can investigate; submitting a request does not guarantee a refund.
## Credit top-ups
Top-ups are one-time purchases, not subscription renewals. Purchased top-up credits are valid for twelve months, so review the credit amount and total on the checkout screen before confirming payment.
:::tip
For billing help, email [vitalik@superappp.com](mailto:vitalik@superappp.com) with your account email and Stripe receipt or invoice ID. Never include complete payment card details.
:::
---
# Keep keys and secrets safe
Source: https://superapp.dev/docs/keys-and-secrets
Anything bundled into an iPhone or Mac app can eventually be inspected. A truly private credential must never live in client code, source control, screenshots, or prompts.
## Public configuration vs. private secrets
Some providers issue client identifiers or publishable keys designed to be included in an app. Administrative tokens, service-role keys, signing secrets, and unrestricted API keys belong in a protected backend.
## Protect production credentials
- Store secrets in Superapp’s secure environment settings or your backend.
- Use separate credentials for development and production.
- Restrict keys by service, app identifier, environment, and quota when supported.
- Rotate a credential immediately if it appears in code, chat, or a public log.
---
# Use Superapp with local coding agents
Source: https://superapp.dev/docs/local-coding-agents
On Mac, a Superapp project is a normal local folder containing a native Swift and Xcode project. You can open that folder in Claude Code, Codex, Xcode, or another local coding agent and continue working with the tools you prefer.
:::tip
This workflow is allowed, but external tools operate outside Superapp's managed environment. Once another agent changes the project, you are responsible for reviewing, testing, and recovering those changes.
:::
## One project, several tools
Superapp, local coding agents, and Xcode can all edit the same files. There is no separate export format to translate: point the other tool at the project folder and ask it to work directly with the Swift code. Keep only one tool actively writing at a time to avoid conflicting edits.
### Product-level iteration
_Superapp_
Describe screens, flows, behavior, and design changes in plain language while Superapp manages the project it generated.
### Direct project access
_Local agents and Xcode_
Inspect files, make precise code changes, run tests, debug builds, and use specialist developer tooling directly on your Mac.
## Use a safe handoff
### 1. Save a known-good version
Confirm the app builds, then create a version-control commit or another recoverable snapshot before giving an external agent write access.
### 2. Open the project folder
Start Claude Code or Codex in the Superapp project folder, or open the Xcode project in an agent-enabled Xcode workflow. Do not copy only a few Swift files into a second folder.
### 3. Give the agent a narrow task
Name the desired result and explicitly protect signing, entitlements, bundle identity, deployment targets, and unrelated project settings unless the task requires them.
### 4. Review the complete diff
Check every changed file before accepting the work. Pay special attention to Xcode project configuration and files the agent did not need to touch.
### 5. Build and test before returning
Run the app in Xcode or Superapp, test the affected flow, and commit the working result. If Superapp was open during the edit, reopen or refresh the project before continuing.
## Changes that need extra care
A coding agent can modify more than Swift source. Seemingly small configuration changes can stop signing, device builds, cloud features, or App Store submission from working.
- **Signing:** development team, certificates, provisioning, and automatic signing settings.
- **Identity:** bundle identifier, product name, targets, schemes, and build configurations.
- **Entitlements:** iCloud, Sign in with Apple, push notifications, HealthKit, app groups, keychain groups, and associated domains.
- **Build environment:** deployment target, package dependencies, build phases, compiler flags, Info.plist values, and generated project files.
- **Connected services:** Supabase configuration, API endpoints, secrets, RevenueCat products, and environment-specific values.
:::note
Superapp cannot guarantee or automatically repair a project environment changed by an external agent. If a tool alters an entitlement or signing setting, diagnosing and reversing that change is the project owner's responsibility.
:::
## A safer agent prompt
```
Work only inside this existing Swift project.
Implement [describe the change] without changing the bundle identifier, signing team, entitlements, deployment target, schemes, build phases, package dependencies, or unrelated project settings.
Before editing, inspect the current structure. After editing, build the existing scheme and summarize every changed file and configuration value.
```
## If the project stops working
1. Stop making additional changes and save the current diff for diagnosis.
2. Compare it with the last known-good commit, especially project and entitlement files.
3. Revert the external change or restore the saved version.
4. Build again before asking Superapp or another agent to continue.
When asking for help, include the build error and a list of changed files. Remove tokens, certificates, private keys, and other secrets before sharing logs or project content.
---
# Manage your subscription
Source: https://superapp.dev/docs/manage-subscription
Your Profile shows the active plan, status, credit balance, and next billing date. Use it as the starting point for every subscription change.
## Open billing controls
1. Sign in to Superapp on the web.
2. Open your Profile.
3. Find the plan and credit sections.
4. Choose Upgrade Plan, Change Plan, Change payment method, or Downgrade.
## Upgrade or change plans
Open the plan selector and compare the current monthly allowance and features. Read the Stripe checkout summary before confirming the amount and renewal schedule. After payment, return to Profile and confirm that the new plan and balance appear.
## Downgrade
A scheduled downgrade takes effect at the billing boundary shown in Profile. Until then, the current plan remains active. Profile displays the destination plan and switch date when a change is pending.
## Cancel
### 1. Choose Downgrade or Cancel Subscription
Open the cancellation flow from Profile and select the reason that best applies.
### 2. Review the alternatives
Superapp may offer a smaller plan when it fits your current use. Read what changes before accepting an alternative or continuing with cancellation.
### 3. Confirm cancellation
The subscription remains active until the displayed end of the current billing period. Profile changes to Cancelled and shows the date access ends.
:::tip
Cancelling a subscription does not delete your Superapp account or projects. You can resubscribe from Profile later.
:::
## Change the payment method
Choose **Change payment method** to open Superapp's secure Stripe billing portal. Superapp support will never ask you to send complete card details through chat or email.
---
# Create effective app videos
Source: https://superapp.dev/docs/marketing-creatives
An effective app video communicates one idea at a time. The first frame earns attention, the demonstration proves the claim, and the ending tells the viewer what to do next.
## Write the brief before filming
- **Audience:** the exact person and situation represented in the video.
- **Hook:** the opening visual or line that makes the problem recognizable.
- **Proof:** the real product action and result shown on screen.
- **Objection:** the main reason a qualified viewer might not try it.
- **Action:** one concrete next step and the destination it leads to.
## Use a simple narrative
```
0–2 seconds: recognizable problem or surprising result
2–8 seconds: real app demonstration
8–12 seconds: proof, reaction, or practical benefit
Final frame: app name and one action
```
## Make it feel native to the creator
Preserve the creator’s normal framing, vocabulary, pace, and humor. Place the app inside a routine, tutorial, comparison, or story they already know how to tell. The person remains the protagonist; the app is the tool that helps them reach the result.
## Create a controlled test matrix
Produce several variations from one base concept. Test different hooks against the same demonstration first, then refine the winning hook with new proof or calls to action. Label every asset so installs and purchases can be traced back to the concept.
:::tip
Never promise a result the product cannot reliably deliver. Clear, repeatable proof builds stronger conversion than exaggerated claims.
:::
---
# Choose what to market
Source: https://superapp.dev/docs/marketing-foundation
Marketing starts before launch. A strong campaign makes one valuable outcome obvious to a specific audience; it does not attempt to explain every screen and capability in the app.
## Anchor the message in behavior
Begin with a moment you can observe: a runner rebuilding the same interval plan, a baker sorting orders from direct messages, or a parent repeatedly checking several calendars. The current workaround gives you the language, stakes, and visual material for marketing.
## Choose a reachable first audience
Define the first group narrowly enough that you know where they gather, what they call the problem, and which result matters. “Freelancers” is broad. “Freelance photographers who prepare client shot lists on iPhone” is a group you can find and speak to directly.
## Write one product promise
```
For [specific person] who [faces a recurring situation],
[app name] helps them [reach a visible result]
without [the frustrating current method].
```
Use the same promise in the App Store subtitle, landing page, creator brief, and opening seconds of a video. Consistency makes each exposure reinforce the last.
## Find the demonstration moment
Choose the shortest interaction that proves the promise on screen. It might be a photo becoming a useful plan, a chaotic list organizing itself, or a live result appearing on Apple Watch. A viewer should understand the before and after without narration.
## Match attention with lasting value
A striking demonstration can earn a download, but repeated utility earns retention. Before scaling promotion, confirm that new users reach the core result and have a reason to return. Measure activation and repeat use alongside views and installs.
:::tip
If the app needs a long explanation, narrow the promise. Marketing becomes easier when one screen recording can show why the product matters.
:::
---
# Marketing resources
Source: https://superapp.dev/docs/marketing-resources
Start with first-party documentation for store assets, experiments, analytics, and endorsement rules. Advice from courses and creators can be useful, but verify claims before building a campaign around them.
## App Store discovery
- [Creating your App Store product page](https://developer.apple.com/app-store/product-page/)— screenshots, previews, descriptions, promotional text, and keywords.
- [Product page optimization](https://developer.apple.com/app-store/product-page-optimization/)— controlled tests for icons, screenshots, and preview videos.
- [App Store asset best practices](https://developer.apple.com/app-store/asset-best-practices/)— current visual guidance and downloadable templates.
## Measurement
- [App Store Connect Analytics Help](https://developer.apple.com/help/app-store-connect-analytics/)— discovery, downloads, engagement, purchases, and subscriptions.
- [Measuring app performance](https://developer.apple.com/app-store-connect/analytics/)— an overview of Apple’s analytics and cohort tools.
## Creator disclosures
- [FTC: Disclosures 101 for Social Media Influencers](https://www.ftc.gov/business-guidance/resources/disclosures-101-social-media-influencers)— plain-language disclosure guidance for endorsements and material relationships.
- [FTC endorsement and review resources](https://www.ftc.gov/business-guidance/advertising-marketing/endorsements-influencers-reviews)— broader guidance for advertisers, platforms, and reviewers.
:::note
Marketing and platform rules change. Recheck the official source before launching a new store experiment, paid creator campaign, or tracking setup.
:::
---
# Monetize your app
Source: https://superapp.dev/docs/monetization
Monetization works best when it follows a clear moment of value. Decide what remains free, what users pay for, and why the paid experience stays worthwhile over time. Superapp can build payments with its integrated RevenueCat workflow or directly with Apple StoreKit.
## Choose the model
- **One-time unlock:** a complete, durable utility or permanent feature.
- **Subscription:** ongoing content, service, storage, or frequent improvements.
- **Consumable:** credits or units a person intentionally uses up and may buy again.
## Choose the payment stack
### RevenueCat
_Integrated_
Best when subscriptions are central to the business and you want managed entitlements, analytics, flexible offerings, or faster paywall iteration.
### Apple StoreKit
_Direct and native_
Best for a focused Apple-only app when fewer dependencies, native system UI, and direct control matter more than a subscription operations layer.
:::tip
Both choices use Apple's In-App Purchase system for digital features sold in an Apple app. RevenueCat does not replace Apple's checkout; it manages subscription state and business tooling around it.
:::
## Build the whole purchase experience
Explain the benefit before the price. Show the billing period and trial terms clearly, provide purchase restoration, and keep the app usable when a purchase is pending, fails, or expires.
- Show the real localized price returned by the store.
- Unlock access only from verified purchase state.
- Include a visible Restore Purchases action.
- Provide links to privacy and terms from the paywall.
- Test purchasing, cancellation, expiration, and restoration before release.
Continue with [RevenueCat or StoreKit?](/revenuecat-vs-storekit) to make the architecture decision before creating products.
:::note
Digital features and content sold inside an Apple app generally need Apple’s in-app purchase system. Confirm the current App Store rules for your specific model.
:::
---
# Move from another AI app builder
Source: https://superapp.dev/docs/move-from-ai-builder
A Lovable, Replit, Bolt, Base44, Bubble, or similar project can become the reference for a native Apple app. Superapp rebuilds the valuable flows; it does not wrap the web output or pretend that React is Swift.
## Collect the product before leaving
- A public preview or a complete screen recording of every important journey.
- Screenshots of signed-in, empty, loading, error, and administrator states.
- Exported assets, copy, data models, and available API documentation.
- The identity provider, backend owner, payment provider, and domain settings.
- A list of known bugs and behaviors that should not be reproduced.
### 1. Define the native scope
Choose what belongs on iPhone and which web-only administration or marketing pages should remain on the existing site.
### 2. Create the first Superapp project
Describe the core user, outcome, and screens. Share the existing app as a reference and state clearly that the output must be native SwiftUI rather than a WebView.
### 3. Reconnect data and services
Connect an owned Supabase project or documented API instead of copying secrets from the old client. Recreate permissions and test with non-production data.
### 4. Compare outcomes
Run the two products side by side. Verify the same user can sign in, find their data, complete the main task, and retain paid access where applicable.
:::tip
Keep the old product available until users and data have a tested transition path. A visual match alone is not a successful migration.
:::
---
# Use native capabilities
Source: https://superapp.dev/docs/native-capabilities
Because Superapp generates native Swift, your project can use the capabilities Apple makes available across iPhone, iPad, Apple Watch, and Mac.
- Camera & photos
- Location & maps
- HealthKit
- Widgets
- Notifications
- Apple Pay
- Sign in with Apple
- AR & sensors
- Watch apps
## How to request a capability
Describe the user benefit and when permission is needed. For example: “Let runners record a route during an active workout. Ask for location permission only when they start their first outdoor run.”
:::tip
Apple requires clear permission descriptions and careful use of sensitive data. Test every permission flow on a real device before submitting the app.
:::
---
# Nightly run and daily report
Source: https://superapp.dev/docs/nightly-run-and-daily-report
Selfdrive works on a daily cycle. The agent runs at night so your morning starts with results, not with work.
## The nightly run
Every night at 03:00 UTC the agent reviews each connected app:
- **Analytics.** Reads the latest App Store Connect data, keeping provisional and incomplete days separate from final ones.
- **Apple Ads.** Checks delivery, spend, bids and keyword results against the campaign you approved.
- **Creator campaigns.** Checks applications, posted videos and views.
- **Scheduled work.** Runs the tasks you approved for tonight, including version submissions.
An hour later, at 04:00 UTC, a second job writes any website articles you approved, so their reports do not wait behind the review.
The **Nightly review** card in your task list shows whether the next run is scheduled and what it will cover.
:::note
The run uses your app's reporting timezone for dates in the report, but the schedule itself is fixed at 03:00 UTC.
:::
## The daily report
After the run, Selfdrive sends one email per connected app. It has a one-line headline and four sections:
| Section | What is in it |
| --- | --- |
| **Results** | Downloads, impressions, product page views and ad results since the last report, with the comparison to the previous period. |
| **Done** | What the agent completed overnight. |
| **Needs you** | Tasks waiting for your approval and decisions such as creator applications. |
| **Waiting** | Work that depends on someone else, such as App Store review or a creator's first video. |
Each item links to the exact place in your workspace. Items that have not changed for several days say so, so you can tell a stuck task from a slow one.
The same message appears in your Selfdrive chat as the agent's morning note, so you can reply to it directly.
## The dashboard
The workspace overview shows first-time downloads, impressions and product page views from App Store Connect, your tasks, customer voice from reviews, competitors and keywords. Numbers for the most recent days are provisional until Apple finalizes them; the agent never treats a missing day as zero.
:::tip
The email arrives after the run finishes, which can take a while on busy nights. Its exact arrival time is not guaranteed.
:::
---
# Onboarding and paywalls
Source: https://superapp.dev/docs/onboarding-and-paywalls
Onboarding should reduce uncertainty between installation and the first useful result. A paywall works best after people understand the product—not after a long sequence designed only to make leaving feel costly.
## Give every screen one job
1. Confirm the problem and outcome in the user’s language.
2. Collect only information required to personalize the first result.
3. Demonstrate the core interaction with real content.
4. Ask for permissions only when the feature needs them.
5. Present the offer with benefits, price, renewal terms, and a clear close action.
## Choose the paywall moment
Test whether users should see the paywall before the core experience, after a preview, or when they attempt to save or repeat a valuable action. Avoid collecting extensive personal information or uploading large files before revealing that payment is required.
## Make the offer understandable
- Describe the paid outcome rather than listing internal features.
- Show billing period, total price, trial length, and post-trial price clearly.
- Keep monthly and annual options visually comparable.
- Provide Restore Purchases and access to subscription management.
- Explain what remains available when a subscription ends.
## Diagnose the funnel in order
Track onboarding start, each meaningful step, paywall view, trial start, purchase, renewal, cancellation, and restoration. A low paywall conversion may actually begin with confusing onboarding or weak acquisition intent; changing the price first will not fix those causes.
:::tip
Change one major variable per test. A new onboarding flow, price, trial, and paywall design launched together may change revenue, but you will not know why.
:::
---
# Post organic content
Source: https://superapp.dev/docs/organic-content
Organic content is a low-risk way to learn which problem, demonstration, and audience make people pay attention. Treat every post as a small experiment, not a verdict on the app.
## Use a repeatable content loop
### 1. Name one audience problem
Open with a recognizable situation, question, mistake, or desired result.
### 2. Show the product doing the work
Record the real app on an iPhone. Move quickly from the problem to the interaction that creates the result, and keep important text inside safe screen areas.
### 3. Make one clear request
Ask viewers to try the app, join TestFlight, comment with a question, or save the post.
### 4. Review and remake
Keep the winning idea and change one variable—the opening line, first frame, length, or call to action—so you learn why it worked.
## Rotate useful formats
- A direct before-and-after demonstration.
- A common mistake followed by the faster workflow.
- A real routine in which the app appears naturally.
- A response to a user question or comment.
- A short story about why you built the app.
- A result, challenge, or progress update created with the app.
## Measure the whole path
Views reveal reach, not business value. Track profile visits, App Store page views, downloads, completed onboarding, trials, purchases, and retention. A smaller post that reaches the right audience can outperform a broad viral post.
:::note
Do not buy engagement or copy another creator’s work. Study patterns such as pacing and structure, then film original content with claims your app can genuinely support.
:::
---
# Fix payment problems
Source: https://superapp.dev/docs/payment-problems
Most billing problems can be resolved from Profile. Start there to confirm the plan status, billing date, and credit balance before retrying a payment.
## Your subscription is past due
1. Open Profile and choose **Update Payment Method**.
2. Replace or correct the payment method in Stripe.
3. Complete any overdue payment, then return to Superapp and refresh Profile.
While an account is overdue, plan changes and credit top-ups may be unavailable. Resolve the payment first, then make the subscription change.
## A card is declined
- Confirm the card number, expiration date, security code, and billing address.
- Complete any verification request from your bank, such as 3D Secure.
- Ask the bank whether online, recurring, or international payments are blocked.
- Try another supported payment method if the bank continues to decline the charge.
## Checkout was closed or cancelled
Return to Profile and check the plan and balance. If neither changed, start checkout again. Review the Stripe confirmation screen before assuming the first attempt completed.
## You paid, but the purchase is missing
1. Refresh Profile, then sign out and back in if the balance still looks unchanged.
2. Wait a few minutes for payment confirmation. Do not immediately buy the same item again.
3. Email [vitalik@superappp.com](mailto:vitalik@superappp.com) with the account email, payment date, amount, and Stripe receipt or invoice ID.
## A charge looks duplicated
Compare the dates and descriptions first: a subscription renewal and a one-time credit top-up can appear close together. If the same purchase appears twice, send both receipt IDs to support for review.
:::note
Never send a full card number, security code, bank password, or verification code to Superapp support. Receipt identifiers are enough to investigate a payment.
:::
---
# Plans and subscriptions
Source: https://superapp.dev/docs/plans-and-subscriptions
Superapp is free to start in most countries. Paid plans add a monthly credit allowance and product features, while one-time top-ups let eligible subscribers handle a temporary burst without moving permanently to a larger plan.
## Current plans
Best for trying Superapp and making smaller changes. Superapp provides free credits to start in most countries; in some regions the free plan is not available. Unused free credits expire at midnight UTC.
Includes 50 monthly credits, automated App Store publishing, Genius Mode, Figma import, email support, and access to custom credit top-ups.
Includes 110 monthly credits, a lower effective cost per credit, and priority support for professional builders.
Includes 230 monthly credits and the lowest standard cost per included credit for people building frequently.
A separate team offering supports shared work, multi-user access, and dedicated support. Contact Superapp from the pricing page to discuss the right setup.
:::note
Prices, allowances, features, currency, and taxes can change. The plan selector and [current pricing page](https://superapp.dev/pricing) are the source of truth before purchase.
:::
## Choose by expected use
- Use Free to learn the workflow or make occasional focused changes.
- Choose Pro for a single active app or a steady personal building habit.
- Choose Business when several features or projects are moving each month.
- Choose Max for frequent, broad, or high-capability agent work.
- Use top-ups for temporary peaks instead of upgrading only for one large week.
Credits measure actual work rather than message count. Read [How credits work](/credits) before estimating a project from the number of prompts alone.
---
# Keep your existing Supabase backend
Source: https://superapp.dev/docs/preserve-supabase
When the existing product already uses a Supabase project you own, the native Superapp client can connect to that backend. This preserves server data while the interface is rebuilt in Swift.
:::note
Do not experiment against production first. Use a separate Supabase project, branch, or safe test environment until authentication, queries, and access policies are verified.
:::
## Document the existing backend
- Tables, views, relationships, functions, triggers, and storage buckets.
- Authentication providers, redirect behavior, and account-deletion requirements.
- Row-level security policies for reading, inserting, updating, and deleting.
- Edge Functions, webhooks, scheduled jobs, and external service dependencies.
- Environment separation, backups, data ownership, and migration history.
### 1. Connect the owned project
Use Superapp's secure Supabase connection flow. Never paste a service-role key into chat or include it in the iOS client.
### 2. Map app actions to permissions
For every screen, specify which signed-in user may read or change each record. Confirm that row-level security enforces those rules rather than relying on hidden buttons.
### 3. Preserve user identity
Keep the same authentication project when existing accounts must continue working. Configure the native sign-in flow and test old accounts, session refresh, sign-out, and account deletion.
### 4. Test compatibility
Verify queries, uploads, realtime updates, functions, and error states with safe data. Check that the old and new clients cannot corrupt each other's records.
### 5. Release gradually
Use TestFlight with existing users before broad release. Monitor authentication errors, policy failures, slow queries, and backend logs during the transition.
Continue with [Connect Supabase](/connect-supabase) for the standard connection flow and [Keep keys and secrets safe](/keys-and-secrets) before adding private integrations.
---
# Preview and iterate
Source: https://superapp.dev/docs/preview-and-iterate
Previewing is part of building. Test after every meaningful change so visual polish never hides a broken or confusing workflow.
## Run a short test pass
1. Start from a clean launch and complete the app’s main task.
2. Try empty states, incorrect input, back navigation, and repeated taps.
3. Check the smallest and largest device sizes you plan to support.
4. Write follow-up prompts from observed behavior, not assumptions.
## Give actionable feedback
```
On the workout detail screen, keep the Start button visible while scrolling.
When a workout has no notes, hide the empty Notes section completely.
```
Mention the screen, the current behavior, and the intended behavior. Attach a screenshot or reference when the visual result is difficult to describe.
---
# Fix preview and runtime problems
Source: https://superapp.dev/docs/preview-runtime-errors
A preview can show an earlier successful build even when the latest build failed. First confirm which version is running, then distinguish preview infrastructure from a problem inside the app.
## The preview is from an earlier version
When Superapp warns that the preview is stale, read the latest build result. Fix the build before evaluating whether the requested visual change appeared. Relaunching an old successful preview cannot make failed code visible.
## The preview is unavailable
1. Wait for the current build and simulator startup to finish.
2. Restart the preview once if it timed out or disconnected.
3. Check whether the latest build itself succeeded.
4. If repeated restarts fail with no build error, preserve the message and contact support.
## The app launches and closes
Treat this as a runtime crash, not a preview refresh problem. Record the last visible screen and action, capture the crash or console message, and reproduce it from a clean launch. Common causes include forced assumptions, missing configuration, unavailable resources, and code that runs too early during startup.
## The app runs but behaves incorrectly
Describe one reproducible path: starting state, exact taps, observed result, and expected result. Test empty, loading, offline, denied-permission, and signed-out states separately.
## Data is missing or does not persist
- Confirm whether the feature uses local storage or a backend.
- Test relaunch, reinstall, sign-out, and a second device as separate cases.
- Verify the active user and environment before changing access rules.
- Do not test a destructive repair against production data.
---
# Privacy, terms, and EULA
Source: https://superapp.dev/docs/privacy-terms-and-eula
Every App Store submission needs public links for privacy and support. Superapp can create these pages from the app you actually built, so you do not have to begin with a blank legal template.
## Use your generated app website
On the web version of Superapp, you can generate a matching website for your app. Superapp uses the app's features and code to draft a privacy policy that reflects what the app collects, stores, and shares. The website also includes a support page, and both pages are linked from its footer.
### 1. Generate the website
During publishing, choose **Generate a website**. Superapp creates the app's public site together with its privacy and support pages.
### 2. Review the details
Confirm the data practices, service providers, contact address, and app name. AI can prepare the policy, but you remain responsible for making sure it describes the released app accurately.
### 3. Publish and copy the links
Publish the website, then use its public `/privacy` and `/support` URLs in the App Store submission. Test both links in a private browser window; Apple must be able to open them without signing in.
:::tip
App website generation is currently available in Superapp on the web and is coming to the Desktop app soon.
:::
## Desktop app: what to do today
For now, ask Superapp's AI to generate a privacy policy for the finished app. Tell it to inspect the app's accounts, analytics, payments, permissions, stored data, and third-party services rather than writing a generic policy.
```
Create a privacy policy for this app based on the code and features it currently uses.
Include the app name, developer contact, data collected, purpose, storage,
third-party services, retention, deletion requests, and children's privacy.
Flag any details I still need to confirm.
```
Publish the result as a public Notion page or Google Doc and paste that URL into App Store Connect. Set sharing to **Anyone with the link can view** and verify that the page opens while signed out. You can use the same approach for terms or a simple support page.
## Privacy policy
Explain what data is collected, why it is used, where it is processed, who it is shared with, how long it is retained, and how a user can request deletion or contact you.
## Terms and license
Terms can define acceptable use, payment conditions, account responsibilities, service limitations, and dispute handling. Review whether Apple’s standard license is sufficient or whether your app needs a custom EULA.
## Match App Store disclosures
App Privacy answers, permission descriptions, age rating, subscription text, and the privacy policy must agree. Recheck them whenever the app adds a data source or SDK.
:::note
Templates are a starting point, not legal advice. Have qualified counsel review policies when the app handles sensitive data, children, regulated activity, or meaningful revenue.
:::
---
# Project settings
Source: https://superapp.dev/docs/project-settings
Project settings define how your app is named, identified, built, and connected to external services.
## App identity
The display name is what people see. The bundle identifier is the permanent technical identity Apple uses to connect builds, capabilities, and the App Store record. Choose it carefully before publishing.
## Secrets and environment values
Keep private credentials out of source code and chat. Use the secure project settings intended for environment values, and separate production credentials from development.
---
# Publish to the App Store
Source: https://superapp.dev/docs/publish-app-store
Superapp guides the technical submission, while you remain responsible for your Apple Developer account, store listing, policies, and the product Apple reviews.
## Before you publish
- Test the complete app on a real device.
- Choose the final app name, icon, and bundle identifier.
- Prepare a privacy policy and support URL.
- Make pricing and subscriptions clear inside the app.
- Have an active Apple Developer Program membership.
### 1. Open Publish
Choose the project you tested and begin the App Store publishing flow in Superapp.
### 2. Connect Apple
Sign in, choose the correct developer team, and complete Apple’s verification when asked.
### 3. Complete the guided steps
Review app information, screenshots, privacy answers, build status, and submission details.
### 4. Finish in App Store Connect
Confirm the product page, review information, territories, and pricing before sending the version to Apple.
## Use the publishing center
- [Create your Apple Developer account](/apple-developer-account) before the first submission.
- Follow the [App Store checklist](/app-store-checklist) before uploading the release candidate.
- Prepare [screenshots and product-page information](/app-store-listing) that match the real app.
- Use [Submission errors](/submission-errors) when a build or version cannot move forward.
- Learn how to [handle review questions and rejections](/app-review) without starting over.
- Ship the next version with [Release updates](/release-updates).
:::note
Apple changes App Store Connect and its review rules over time. Superapp handles the build and guided submission, but Apple's current requirements remain the final authority.
:::
---
# Move from React Native or Expo to Swift
Source: https://superapp.dev/docs/react-native-to-swift
Superapp does not translate JavaScript line by line. It uses the existing product, screens, and service contracts as a specification, then creates a native Swift and SwiftUI implementation.
## Separate the client from the product
- Document navigation, screens, validation, and offline behavior.
- List every Expo SDK feature and third-party native module.
- Record API endpoints, request shapes, responses, and authentication behavior.
- Identify local storage that must migrate and server data that can remain.
- Map deep links, notifications, analytics events, and subscription entitlements.
## Replace abstractions intentionally
### Keep
Product rules, content, backend contracts, user accounts, remote data, brand assets, and subscription state when they are portable and correctly owned.
### Rebuild
React components, navigation, device modules, local persistence, permission handling, build configuration, and other client-side platform code.
### 1. Rebuild the core loop
Start with one complete flow in native SwiftUI and connect it to a development backend.
### 2. Replace native modules
Map each Expo or React Native dependency to an Apple framework or a maintained Swift package. Prefer direct Apple APIs for capabilities such as notifications, location, camera, HealthKit, widgets, and purchases.
### 3. Test migration behavior
Verify existing accounts, server records, subscription restoration, links, and push tokens. Test both fresh installs and upgrades where a released bundle is being replaced.
### 4. Retire the old client carefully
Keep the cross-platform codebase and release artifacts recoverable until the Swift app is stable in TestFlight and production.
---
# Rebuild an existing app
Source: https://superapp.dev/docs/rebuild-existing-app
Rebuilding is a product migration, not a file conversion. Preserve what users value, discard accidental complexity, and prove each native journey against the existing app.
## Create a migration inventory
- Every screen, route, empty state, error, and permission request.
- Authentication providers, account lifecycle, roles, and access rules.
- Database entities, APIs, file storage, scheduled work, and notifications.
- Purchases, subscriptions, entitlements, trials, and restoration behavior.
- Analytics events, deep links, widgets, and other system integrations.
### 1. Choose the first complete journey
Rebuild one end-to-end outcome before copying every settings screen. A narrow working path exposes architectural differences early.
### 2. Bring reliable references
Attach screenshots, design files, data models, API documentation, and acceptance criteria. Never include production credentials or real customer data.
### 3. Connect existing services
Reuse a backend only after documenting its contracts and permissions. Keep the old app live while the native client is tested against a safe development environment.
### 4. Compare and cut over
Test old and new versions side by side, migrate or preserve user data, distribute a TestFlight beta, and release only when core behavior is equivalent or intentionally improved.
:::note
Keep the existing app and its production backend recoverable until the new App Store version has been installed and verified by real users.
:::
---
# Release updates
Source: https://superapp.dev/docs/release-updates
An App Store update is a new reviewed version of the existing app. Keep the same app record and bundle identifier, choose a higher version, test the migration path, and explain what changed.
### 1. Prepare the update
Finish the changes and test both a fresh install and an upgrade from the current public version. Protect existing accounts, saved data, subscriptions, and database migrations.
### 2. Start a new version in Superapp
Open the existing project's publishing flow. Superapp keeps the App Store Connect app identity and guides you to a higher marketing version when the previous one is locked.
### 3. Build and test the exact candidate
Upload the build, wait for processing, and install it from TestFlight. Recheck sign-in, purchases, notifications, stored data, and the feature changed by this release.
### 4. Update the product page
Add required What's New notes, replace screenshots when the interface changed, and update privacy answers, support content, pricing, or review notes when necessary.
### 5. Submit and choose release timing
Send the new version to review, then choose the appropriate App Store Connect release option: manual, automatic, or phased when available for the release.
## Write useful release notes
Describe changes people can recognize. “You can now edit saved workouts and sync them to Apple Watch” is more useful than “bug fixes and improvements.” Keep internal implementation details out of customer-facing notes.
## After release
- Confirm the version appears in the intended storefronts.
- Install it from the public App Store and complete a smoke test.
- Monitor crashes, sign-in failures, purchase errors, and support messages.
- Keep the previous release notes and build reference for incident investigation.
- Prepare a focused follow-up rather than changing several unrelated systems at once.
:::tip
Apple notes that an approved version can take time to appear across all selected storefronts. A short delay after approval does not necessarily mean publishing failed.
:::
---
# Build with RevenueCat
Source: https://superapp.dev/docs/revenuecat-paywalls
RevenueCat is integrated with Superapp. Use it when you want Superapp's AI to help create and manage a subscription setup that can evolve after the first release.
## Understand the model
- **Product:** the item and price configured in App Store Connect.
- **Entitlement:** the access level your app unlocks, such as Premium.
- **Offering:** the set of packages shown to a particular customer.
- **Paywall:** the screen that explains the value and presents the offering.
### 1. Define the access rule
Decide exactly what the paid entitlement unlocks. Keep this independent from a specific monthly or annual product so pricing can change without rewriting feature checks.
### 2. Connect RevenueCat
Ask Superapp to add RevenueCat and complete the secure connection to your RevenueCat account. Select the intended project when more than one is available.
### 3. Create and map the products
Create the corresponding products in App Store Connect, then connect them to the RevenueCat entitlement and offering. Product identifiers must match exactly.
### 4. Build the paywall and access checks
Ask Superapp to present the active offering, handle purchase states, and unlock premium features from the entitlement—not from a locally saved button tap.
### 5. Add customer controls
Include Restore Purchases, subscription management, clear errors, and a signed-in user identity when access must follow an account across devices.
## Where RevenueCat provides the most value
Offerings can separate product configuration from the app interface. This is useful when testing monthly versus annual emphasis, showing different packages at different moments, or evolving a paywall without hardcoding a fixed product list into the app.
:::note
RevenueCat configuration does not replace App Store Connect. Prices, subscription groups, introductory offers, review information, and Apple approval still begin with Apple.
:::
---
# RevenueCat or StoreKit?
Source: https://superapp.dev/docs/revenuecat-vs-storekit
RevenueCat and StoreKit are not competing payment processors. Apple still handles the transaction. The decision is whether your app manages purchase state directly with StoreKit or uses RevenueCat as an additional subscription-management layer.
## The practical difference
RevenueCat turns App Store products into named entitlements, keeps customer purchase state available through its SDK and APIs, and adds dashboards, offerings, paywall management, targeting, and subscription analytics. Superapp can work with the connected RevenueCat project through its built-in integration.
The app talks directly to Apple's StoreKit APIs. It can use native StoreView, ProductView, or SubscriptionStoreView components and determine access from Apple's signed transactions and subscription status without adding RevenueCat.
Products and subscription groups must be configured in App Store Connect. The app still needs correct purchase, entitlement, expiration, restore, and error handling, and every product must pass App Review.
## Choose RevenueCat when your goal is growth
- You expect several products, plans, paywalls, or customer segments.
- You want to change offerings or supported paywall content without shipping app code.
- You need subscription analytics, customer history, webhooks, or backend access checks.
- You may expand beyond one Apple app or platform later.
- You want Superapp's integrated RevenueCat tools to help configure the system.
## Choose direct StoreKit when your goal is simplicity
- You have one Apple-only app with a small, stable product catalog.
- You want Apple's native subscription UI and localized merchandising.
- You prefer fewer third-party services and less customer data leaving Apple's stack.
- You are comfortable keeping entitlement and lifecycle logic correct in the app.
- You do not need advanced paywall analytics, targeting, or remote experiments.
## A simple rule
### Start with StoreKit
_Ship the simplest reliable version_
A single premium unlock or one straightforward subscription can stay entirely native.
### Start with RevenueCat
_Build a subscription business_
If pricing, retention, segmentation, and paywall iteration are core product work, use the operational layer from the beginning.
:::note
“Apple paywall” here means a paywall built with StoreKit. Apple Pay is a different payment technology and is generally for physical goods, services, and other eligible commerce—not for unlocking digital app features.
:::
---
# What Selfdrive does
Source: https://superapp.dev/docs/selfdrive
Selfdrive is Superapp's AI marketing agent for apps on the App Store. You connect an app, approve a growth plan, and the agent works on it every night across four channels: Apple Ads, App Store optimization, your website with SEO and GEO, and creator campaigns. Every morning you get one email with what changed and what needs you.
:::note
Selfdrive is in beta. Creator campaigns are in alpha.
:::
## Who it is for
Anyone with an app live on the App Store. You can connect an app you built in Superapp or any app you publish from your own Apple Developer account. Selfdrive does not support Android or Google Play.
## The four channels
| Channel | What the agent does |
| --- | --- |
| **Apple Ads** | Proposes search campaigns, keeps spend inside the budget you approve, tunes bids and keywords, and pauses what is not working. |
| **ASO** | Researches keywords from App Store data, your analytics and your Apple Ads results, then drafts listing updates for you to approve. |
| **Website, SEO and GEO** | Builds your app's website, researches what ChatGPT answers for your category, and writes articles so your app is found on Google and in AI answers. |
| **Creator campaigns** | Writes the brief, recruits creators, reviews applications and videos, and pays creators only for performance on videos you approve. |
Each channel has its own page in this section.
## How it works
1. **Connect your app.** Paste its App Store link, pick an app you built in Superapp, or sign in with the Apple Developer account that publishes it. See [Connect your app](/connect-your-app-to-selfdrive).
2. **Get a growth plan.** The agent studies your listing, keywords, reviews, competitors and analytics, then proposes tasks in chat. The plan is free.
3. **Approve what you want.** Tasks you approve are scheduled. Tasks you skip stay out of the way. See [Tasks and approvals](/selfdrive-tasks-and-approvals).
4. **It works every night.** At 03:00 UTC the agent runs its nightly review, executes approved work and prepares new proposals. See [Nightly run and daily report](/nightly-run-and-daily-report).
5. **You wake up to a report.** One email: results, what was done, what needs your decision, and what is waiting on Apple or creators.
## What it never does without you
- It never changes your App Store listing, submits a version, launches a campaign, briefs a creator or publishes an article until you approve that task.
- Ad spend goes to Apple from your own Apple Ads account, inside the budget you approved.
- Creators are paid only for videos you approve, and only for the views those videos earn.
- Your Apple sign-in is stored encrypted and your password is never stored. You can revoke access at any time.
## Pricing
Selfdrive is included in the **Max** plan at $100 per month, which also gives you 230 credits for building apps. Connecting an app and getting the growth plan is free; approving and running tasks needs Max. Apple ad spend and creator payouts are separate and only happen within budgets you approve. See [Plans and subscriptions](/plans-and-subscriptions) and [Credit top-ups](/credit-top-ups).
:::tip
Already on Max? Selfdrive is in your plan. Open **Selfdrive** in the navigation and connect your first app.
:::
---
# Apple Ads
Source: https://superapp.dev/docs/selfdrive-apple-ads
Selfdrive runs Apple Search Ads campaigns for you: it proposes the campaign, keeps spend inside the budget you approve, tunes bids and keywords, and pauses what is not working. The results also feed your App Store listing, so keywords that convert in ads can bring organic installs too.
## Connect your Apple Ads account
Open the **Apple Ads** tab and sign in with your Apple ID. Selfdrive asks Apple for access to your Apple Ads account and shows the ad accounts you can use. Ad spend is billed by Apple to that account, never through Superapp.
You can disconnect Apple Ads for all your apps from the same tab.
:::note
Apple Ads does not run in every country. The agent can only propose campaigns for storefronts available in your account.
:::
## What a campaign proposal contains
A campaign is a task you approve. It names the markets, the daily budget, the currency and one of two strategies:
- **Manual.** Up to ten keywords you can see, each with exact or broad match and its own maximum cost per tap. Search Match is off, so Apple does not add keywords on its own.
- **Automatic.** Apple's maximize-conversions bidding with a target cost per install, plus Search Match.
Keyword ideas come from Apple's own suggestions for your storefront and from your ASO research. The agent never invents a bid source.
## What happens after approval
- The campaign launches inside the terms on the task. Changing the budget, keywords or bids is a new task that shows the full desired configuration, so you always see what will change.
- Pausing and resuming are tasks too. A direct instruction in chat ("pause ads") runs immediately.
- The agent waits for real evidence before judging a campaign: at least 14 days, 100 impressions, 10 taps and 3 attributed installs. Below that it reports delivery, not conclusions.
- Every morning the report shows spend against the budget, installs, cost per install and what was paused.
## Budget rules
- You set the daily budget on the task. The agent cannot raise it without a new approval.
- Spend is paid to Apple from your account. Superapp credits are not used for ad spend.
- Pausing a campaign does not refund spend already incurred.
:::tip
Start with one market and a budget you can leave alone for two weeks. The agent needs that time to get enough data to optimize.
:::
---
# App Store optimization
Source: https://superapp.dev/docs/selfdrive-aso
Selfdrive's ASO work is evidence-based: it reads what people search for, where your app ranks, what your listing says and how it converts, then proposes changes you approve before anything is published.
## What it reads
- **Your public listing** in each storefront: name, subtitle, description, screenshots and ratings.
- **Keyword ranks.** Where your app appears in App Store search results, checked within the top 50 for each keyword.
- **Keyword ideas and metrics.** Apple's autocomplete and suggestion data, with popularity as a relative score, not a search volume.
- **App Store Connect metadata and analytics** when connected: impressions, product page views, downloads and conversion.
- **Competitor listings** you track in the workspace.
- **Apple Ads results** when connected. Keywords that bring installs in ads are strong candidates for your listing.
- **Reviews**, which feed the customer voice section of your dashboard.
Missing or stale data is reported as missing. The agent never fills a gap with a guess.
## What it proposes
| Task | Result |
| --- | --- |
| Keyword opportunity | A keyword worth targeting, with its rank, popularity and the evidence behind it. |
| Metadata improvement | A new title, subtitle or keyword field drafted for a specific storefront. |
| Listing refresh | A broader update when the listing has drifted from what people search for. |
| Store listing change | The approved change, applied to the version Apple will accept. |
A listing change is drafted against your current App Store Connect metadata. If an editable version already exists in App Store Connect, the change is proposed for that version rather than creating a conflicting one.
## Approval
Nothing is published until you approve the task. Approved changes are applied in the next nightly run, and the daily report confirms what changed. Listing changes take effect when Apple processes them, and ranking effects usually take weeks.
## Version submissions
The agent can also submit a build for App Store review as a task, with release notes, either immediately or tonight. It needs App Store Connect access and a build ready in TestFlight. See [Publish to the App Store](/publish-app-store) for the submission flow itself.
:::note
Selfdrive does not promise rankings. It reports what changed and what the data shows, and proposes the next step.
:::
---
# Creator campaigns
Source: https://superapp.dev/docs/selfdrive-creator-campaigns
Selfdrive runs short-form creator campaigns for your app: it writes the brief, recruits creators, reviews their applications and videos, messages them, and pays only for performance on videos you approve.
:::note
Creator campaigns are in alpha. Creator recruitment, messaging and payouts run through Viral, Superapp's creator platform.
:::
## Launching a campaign
The **Creator campaign** task holds everything the campaign will run on:
- the campaign name and a product description creators see;
- the platforms, such as TikTok or Instagram;
- the start date and how many videos each creator posts per week;
- the CPM rate and bonus mode;
- the maximum number of creators and the selection criteria.
Approving the task opens recruitment. It does not hire anyone.
## Hiring creators
Creators apply to your campaign. For each application the agent writes a recommendation from the creator's profile, audience and past videos, and you decide in the **Applications** tab. Every hire and every rejection is your explicit decision; the agent never hires on its own. Audience markets come from your criteria, never from a creator's name or appearance.
Once hired, the agent messages creators with the brief, answers their questions and follows up on posting schedules. You can read the conversations in the **UGC** tab.
## How creators are paid
Compensation is performance-based only. There is no base pay, per-post fee or retainer.
- **CPM.** Creators earn the approved rate per 1,000 views each video gets above its first 200 views.
- **Bonuses.** Each video earns a flat bonus when it passes a view milestone: $50 at 50,000 views, $100 at 100,000, $250 at 250,000, $450 at 500,000 and $850 at 1,000,000. The campaign's bonus mode sets whether a video collects every milestone it passes or only the highest.
- **Cap.** Each creator has a weekly payout cap.
The task shows a payout preview before you approve. Creators are paid only for videos you approve, and payouts are settled through Viral, separately from your Superapp plan.
## Stopping a campaign
Ask the agent to stop the campaign, or approve the **End campaign** task it proposes. Recruitment closes, running videos finish their payout windows, and the daily report tracks the final results. An app with a running campaign cannot be deleted until the campaign is stopped.
:::tip
Ten to twenty creators testing different hooks beat one perfect video. Approve a few, see which hooks drive installs, then scale those.
:::
---
# Website, SEO and GEO
Source: https://superapp.dev/docs/selfdrive-seo-and-geo
Selfdrive gives your app a website on your own domain and fills it with articles aimed at two readers: search engines and AI assistants. GEO, generative engine optimization, means writing the kind of page ChatGPT cites when someone asks for an app like yours.
## The website
If you built the app in Superapp and generated a website, Selfdrive uses it. Otherwise the **Website setup** task creates one from your App Store listing in a Superapp project, and the **Website domain** task connects a domain you control. You need access to the domain's DNS settings. See [Generate your app website](/app-website) for how the website itself works.
## Research: what ChatGPT answers
The **SEO prompt research** task is the core of GEO. The agent writes 40 to 50 prompts across 5 to 7 topics, the way a person would type them into ChatGPT to end up at a product like yours: keyword searches, natural questions, requests for recommendations and constraints such as price or platform. The prompts find your category, never your brand name.
After you approve the task, Selfdrive runs each prompt through ChatGPT in the background. This takes several minutes, and the agent messages you in chat when it is done. The result shows, for every prompt:
- the answer ChatGPT gave and the products it recommended;
- the pages it cited, which are what it trusts today for that question;
- the web searches it ran to answer.
Pages that are cited again and again show the article shapes that win, often comparisons and lists. A prompt with no searches means the model answered from memory; that is reported as "no searches seen", not as zero interest.
## The content plan
From the research the agent proposes a list of articles. Each one is written to answer a question people actually ask and to be the kind of page AI assistants cite. In the **SEO** tab you approve or remove articles; nothing else moves them.
Approved articles are written by a job that runs at 04:00 UTC, an hour after the nightly review, and published to your website. The agent reports each one in chat.
## What to expect
- The research runs once per request. It is not daily tracking and has no visibility score.
- Search engines and AI assistants decide what they index and cite. Selfdrive reports what it published and what the research showed, and does not guarantee rankings or mentions.
- Content takes months to compound. Pair it with Apple Ads or ASO for faster results.
:::tip
Keep the articles honest about what your app does. Claims the app cannot back up hurt both trust and citations.
:::
---
# Tasks and approvals
Source: https://superapp.dev/docs/selfdrive-tasks-and-approvals
Everything Selfdrive does is a task. The agent proposes tasks with the evidence behind them; you decide which ones run. Nothing goes live from a proposal alone.
## Where tasks come from
- **The growth plan.** After you connect an app, the agent researches it and proposes a first set of tasks in chat.
- **The nightly run.** Each night the agent reviews analytics, campaigns and rankings and proposes new tasks when it finds something worth doing. See [Nightly run and daily report](/nightly-run-and-daily-report).
- **Your instructions.** Ask for something in chat, such as "pause the ads campaign" or "submit version 1.0.2 for review". The agent saves it as an exact task and, because you asked for it, runs it right away. It only asks back when a material detail is missing.
Every task shows its objective, the evidence it is based on, and what it will change.
## Task types
| Type | What it does |
| --- | --- |
| Investigate finding | Looks deeper into something the agent noticed, without changing anything. |
| ASO keyword opportunity, metadata improvement, listing refresh | Researches and drafts listing improvements. See [ASO](/selfdrive-aso). |
| Store listing change | Applies an approved change to your App Store listing. |
| Version submission | Submits a build and release notes for App Store review, now or during the night. |
| Apple Ads campaign, update, status | Creates, changes, pauses or resumes a campaign. See [Apple Ads](/selfdrive-apple-ads). |
| Creator campaign, end campaign | Launches or stops creator recruitment. See [Creator campaigns](/selfdrive-creator-campaigns). |
| SEO prompt research, website setup, website domain, SEO article | Researches what ChatGPT answers, builds the website, connects your domain and writes articles. See [SEO and GEO](/selfdrive-seo-and-geo). |
Apple Ads and creator tasks involve money. They always run inside the budget and terms written on the task you approved.
## Statuses
| Status | Meaning |
| --- | --- |
| Proposed | Waiting for your decision. |
| Accepted | You approved it. |
| Scheduled | Queued for the next nightly run or for a background job. |
| Running | In progress. |
| Blocked | Needs something first, usually a connection or a decision from you. The task says what. |
| Failed | Did not complete. The task keeps the error so you or the agent can retry. |
| Completed | Done. The result shows in the task and in the next daily report. |
| Dismissed | You skipped it. |
## Approve, skip or dismiss
- **Approve** a task from its card or by telling the agent in chat. Approving needs the Max plan. See [What Selfdrive does](/selfdrive#pricing).
- **Review** opens the full task with its evidence and exact changes.
- **Skip** or dismiss tasks you do not want. You can say why (not useful, already done, or wrong) so the agent proposes better ones.
:::note
If a task changes after you looked at it, for example because the nightly run found new evidence, Selfdrive asks you to review the latest version before it starts.
:::
## Now or tonight
Most tasks run in the next nightly run. Version submissions can run immediately or tonight, whichever you choose. When you give a direct instruction in chat, the agent runs it now.
---
# Share and collaborate
Source: https://superapp.dev/docs/share-and-collaborate
Good collaboration starts with a stable build and a focused request. Share enough context for someone to evaluate the product without giving them access they do not need.
## Ask for a useful review
Name the flow, the intended user, and the decision you need help with. Provide a TestFlight build for realistic testing and keep visual feedback separate from functional bugs.
## Prepare a developer handoff
- Commit the working project and document how to run it.
- List external services, environments, and required Apple capabilities.
- Transfer access through each provider instead of sending credentials.
- Record known limitations and the next intended milestone.
---
# Fix signing and entitlement errors
Source: https://superapp.dev/docs/signing-entitlement-errors
Signing connects the app, bundle identifier, Apple Developer team, certificate, profile, and requested capabilities. Changing several of them together can turn one configuration issue into a new project identity.
## Protect the app identity
:::note
Do not change the bundle identifier, create a replacement App ID, revoke certificates, or remove entitlements just to make an error disappear. Confirm the intended identity first.
:::
## Check in this order
1. Confirm the correct Apple Developer team is selected.
2. Verify the membership is active and pending Apple agreements are complete.
3. Match the project bundle identifier to the intended App ID and App Store record.
4. Confirm each requested capability is enabled for that identifier.
5. Check that the entitlements file and provisioning profile agree.
6. Reconnect the Apple account if authorization expired, then rebuild.
## Typical capability failures
- Sign in with Apple capability or return configuration is missing.
- Push notification entitlement is absent or uses the wrong environment.
- App groups, keychain groups, or associated domains do not match the developer portal.
- iCloud, HealthKit, or another restricted capability is not enabled for the App ID.
- An external coding agent changed the signing team or entitlements.
## Certificate limits
If Apple reports a certificate limit, identify which certificate belongs to the current setup before revoking anything. Revocation can break other apps, developers, or Xcode installations using that certificate.
:::tip
Test capability changes on a real device. A Simulator build does not prove that provisioning, push notifications, Apple authentication, or device entitlements work.
:::
---
# Build an Apple StoreKit paywall
Source: https://superapp.dev/docs/storekit-paywalls
A direct StoreKit paywall keeps the purchase architecture inside Apple's frameworks. It is a strong fit for a focused Apple-only app with a small catalog and stable pricing strategy.
## Choose the native presentation
- **ProductView:** present one product using Apple-provided purchase behavior.
- **StoreView:** merchandise a collection of in-app purchase products.
- **SubscriptionStoreView:** present plans in an App Store Connect subscription group, including eligible introductory offers.
- **Custom SwiftUI paywall:** design the complete interface while using StoreKit for product data, purchases, and verified access.
### 1. Create products in App Store Connect
Choose the product type, identifiers, pricing, localization, and subscription group. Keep a record of every exact identifier used by the app.
### 2. Ask Superapp for StoreKit 2
Describe what is paid, when the paywall appears, and whether you want Apple's native subscription view or a custom SwiftUI design.
### 3. Unlock from verified state
The app must evaluate verified transactions and current subscription status whenever protected content appears. Never grant permanent access from a local preference alone.
### 4. Handle the lifecycle
Account for pending purchases, cancellation, expiration, billing retry, revocation, upgrades, downgrades, and restored purchases.
## The tradeoff
StoreKit removes an external subscription service and gives you native Apple UI, but the app owns more of the state model, diagnostics, analytics, and backend coordination. A custom paywall change may also require a new app release when its content is hardcoded.
:::tip
Ask for a direct StoreKit implementation explicitly. If your request emphasizes subscription analytics, remotely managed paywalls, or cross-platform entitlements, RevenueCat is usually the better fit.
:::
---
# Fix submission errors
Source: https://superapp.dev/docs/submission-errors
A submission error usually belongs to one of four layers: the Apple account, the app identity, the uploaded build, or the App Store Connect record. Read the exact message before changing anything.
Sign in to Apple Developer and App Store Connect as the Account Holder. Accept pending agreements, confirm the membership is active, then reconnect the correct team in Superapp.
Confirm that the bundle identifier in Superapp is identical to the identifier owned by the selected Apple team and attached to the intended App Store Connect app. Do not create a second record to work around a typo.
Apple must process each upload. Wait for the exact build number, then check for an email from Apple describing a processing failure. Upload a new build only after resolving that reason.
Open the app's App Privacy section in App Store Connect, complete the data-use questionnaire, and click Publish. Saving answers without publishing them is not enough.
Every update after the first release needs release notes. Add a concise description of user-visible improvements and fixes, then submit again; the existing upload can remain.
A version already used for a completed review cannot accept a different release. In Superapp, bump to the suggested marketing version, rebuild, and upload the fresh build.
Read Apple's message in App Store Connect. Reply if the reviewer needs information, or withdraw the open submission before submitting a different version. Withdrawing does not delete the app or its metadata.
Verify the selected team, bundle identifier, certificates, and capabilities. A feature such as push notifications, Sign in with Apple, HealthKit, or associated domains must be enabled consistently for the identifier and the build.
Complete every highlighted field, including category, description, keywords, pricing, reviewer contact details, support URL, privacy URL, and demo credentials when sign-in is required.
## When you ask for help
Copy the complete error, name the publishing step, and include the marketing version and build number. Never send your Apple password, verification code, private key, or signing certificate.
---
# Subscriptions and free trials
Source: https://superapp.dev/docs/subscription-trials
A trial should let someone experience the paid value before billing begins. Configure the offer in App Store Connect and design the paywall around the real eligibility and price returned by Apple.
## Design the subscription first
- Name the recurring value customers continue receiving.
- Keep plans for the same service inside one subscription group.
- Rank access levels correctly so upgrades and downgrades behave as intended.
- Choose monthly and annual options only when each helps a real customer goal.
## Configure the free trial
1. Create an introductory offer for the subscription in App Store Connect.
2. Choose the eligible product, trial duration, territories, and availability.
3. Make the StoreKit or RevenueCat paywall react to Apple's eligibility result.
4. Test eligible and previously subscribed accounts separately.
:::note
Do not implement an auto-renewable subscription trial with a custom countdown. Apple determines introductory-offer eligibility and applies the approved offer during purchase.
:::
## What the paywall must communicate
- The specific features or service included.
- The trial duration when the customer is eligible.
- The localized price and billing period after the trial.
- That the subscription renews automatically until cancelled.
- A clear purchase action plus privacy and terms links.
## When to skip a trial
A free trial is not automatically better. Skip it when the paid value is immediate and obvious, the product is a one-time utility, or trial users would create significant variable cost before understanding the product. A useful free tier or preview may explain value more clearly.
---
# Superapp Cloud
Source: https://superapp.dev/docs/superapp-cloud
Superapp Cloud is the managed backend built into Superapp. It supports app features that need accounts, shared data, synchronization, file storage, or trusted server-side work without requiring you to deploy and maintain the infrastructure yourself.
## The default backend on Superapp Web
Web projects use Superapp Cloud as their standard backend path. You describe the product behavior and data rules in the same workspace where you build the app; Superapp handles the managed cloud setup behind that experience.
## Why AI works better with Superapp Cloud
Superapp Cloud is a closed, managed system with a backend structure the Superapp AI already understands. The AI knows how authentication, data, storage, permissions, and server-side operations fit together, so it can make coordinated changes instead of guessing how a custom environment is configured.
- The available services and supported patterns are known in advance.
- Configuration stays consistent between the app and its backend.
- Schema and access-rule changes can be planned together.
- There are fewer custom settings, versions, and external modifications to diagnose.
:::tip
For the most reliable AI building experience, use Superapp Cloud. Self-hosted Supabase is intended for teams that need direct infrastructure control and are comfortable owning the additional configuration.
:::
## What it provides
- **Authentication:** accounts and sessions for identifying app users.
- **Database:** durable records that can synchronize between devices.
- **Storage:** uploaded images, documents, audio, and other user files.
- **Access rules:** control over who may read or change each kind of data.
- **Server-side work:** trusted logic for integrations, private keys, and incoming events.
## Model the product before the tables
Explain what each person creates, what must persist, and who can see or change it. Superapp can translate those product rules into a data model and protected operations.
```
Add accounts and shared training plans.
Coaches create and edit plans for athletes assigned to them.
Athletes can read their own plans and mark workouts complete, but cannot edit the plan itself.
Keep progress synchronized across iPhone and Mac.
```
## Make access explicit
Treat data as private unless the product requires sharing. Define ownership for every record, check permissions on the backend, and test with two separate accounts. Hiding a button in the interface does not prevent an unauthorized request.
## Using Superapp for Mac
Mac projects can use Superapp Cloud for the managed experience or connect to a self-hosted Supabase project. Choose self-hosting when you need direct infrastructure ownership, custom operations, or an environment already managed by your team.
### Choose Superapp Cloud
_Managed_
Best AI results and the shortest path from product requirements to a working backend.
### Choose Supabase
_Self-hosted_
Best when your team wants to operate the database and backend environment directly.
## Move an existing project to self-hosted Supabase
An existing Superapp Cloud project may already depend on managed authentication, database tables, access policies, storage, and server-side logic. Moving only the app's connection details can separate it from those services or expose data incorrectly.
This migration is therefore handled by the Superapp team on request. Contact [vitalik@superappp.com](mailto:vitalik@superappp.com) from the email associated with your account. Include the project name and why you want to self-host, but do not send passwords, service-role keys, or other private credentials by email.
:::tip
Connecting a new Mac project to Supabase and migrating an existing Superapp Cloud project are different workflows. Use the normal connection flow only for a new project or when the Superapp team instructs you to do so.
:::
## Work carefully with live data
Separate development and production data, test schema and permission changes before release, and back up important records before destructive operations. Use server-side secrets for privileged integrations and never ship them inside the app.
:::note
A local-only app may not need Superapp Cloud at all. Read [Do you need a backend?](/backend) before adding accounts or shared infrastructure to an early prototype.
:::
---
# Collect diagnostics and contact support
Source: https://superapp.dev/docs/support-diagnostics
A useful support report lets someone reproduce the problem and identify the failing version without asking you to repeat the entire story.
## Include these details
- Your Superapp account email and project name.
- Whether you are using Superapp Web or Mac.
- The exact steps from a clean starting state to the failure.
- What you expected and what happened instead.
- The first exact error plus a screenshot or short recording when useful.
- Device model, OS version, and whether Simulator, device, or TestFlight is affected.
- The last time or project version known to work.
## Remove sensitive information
Redact passwords, API secrets, private keys, signing certificates, recovery codes, service-role keys, access tokens, and personal customer data. A bundle identifier, non-secret error message, or Stripe receipt ID is normally enough to locate the relevant system without sharing credentials.
## Make the scope obvious
### One version or feature fails
_Project-specific_
Include the last change, affected files or screen, and a reliable reproduction path.
### Several projects fail
_Platform or account_
Include the time, connection state, account status, and whether another device works.
Email [vitalik@superappp.com](mailto:vitalik@superappp.com). If the issue concerns an external tool that edited a Mac project, include a summary of its changed files and configuration values.
---
# Test and restore purchases
Source: https://superapp.dev/docs/test-and-restore-purchases
A successful first purchase is only one state. A production-ready app must continue granting the correct access after relaunch, reinstall, device changes, cancellation, renewal problems, and restoration.
## Always provide Restore Purchases
Put a visible Restore Purchases action on the paywall or account screen. Run restoration only after the user chooses it, show progress, and explain whether access was recovered or no eligible purchase was found.
### Restore the customer entitlement
_RevenueCat_
Trigger RevenueCat's restore flow, then unlock from the returned active entitlement. Use a consistent app user ID when purchases should follow an app account.
### Synchronize with the App Store
_StoreKit_
Refresh Apple purchase state, evaluate verified current entitlements, and update the interface from that result.
## Test in stages
### 1. StoreKit configuration in Xcode
Exercise the interface and transaction states locally before the App Store products are ready. This is fast but does not prove the production configuration.
### 2. Apple sandbox
Use sandbox accounts with the real App Store Connect products. Check identifiers, eligibility, renewal, expiration, and billing states without a real charge.
### 3. TestFlight
Test the signed distributed build on a real device. Confirm the complete purchase, relaunch, restore, and subscription-management experience.
## Minimum test matrix
- New purchase succeeds and unlocks the intended feature.
- The customer cancels the purchase sheet without losing app state.
- A pending or failed purchase shows a recoverable message.
- Access survives relaunch and reinstall.
- For non-consumables and subscriptions, Restore Purchases works on another device using the same App Store account.
- Consumables are not restored by StoreKit. If credits must follow the customer across devices, persist and reconcile the account-backed balance separately.
- Expiration or revocation removes access at the correct time.
- Upgrade and downgrade behavior matches the subscription-group levels.
- The paywall reflects trial eligibility and normal pricing correctly.
:::note
StoreKit configuration, sandbox, and TestFlight each prove different things. Complete all three stages before trusting the production purchase flow.
:::
---
# Test on your device
Source: https://superapp.dev/docs/test-on-your-device
The simulator is excellent for fast interface work, but a real device reveals the details that matter before release: touch behavior, permissions, camera access, notifications, performance, signing, and Sign in with Apple.
## Choose the right testing path
### Connect your device
_Fast iteration_
Use the QR flow on Superapp Web or a USB cable on Superapp for Mac while you are actively building.
### Use TestFlight
_Release confidence_
Install an Apple-hosted beta to test distribution, production signing, purchases, and the experience your testers will receive.
:::tip
Use direct device testing for the daily build loop, then use TestFlight for milestone builds and testing with other people.
:::
## Superapp Web: connect with a QR code
### 1. Open the device connection flow
Open your project’s preview controls and choose **Connect your device**. Superapp displays a QR code for the current project.
### 2. Scan the code on your device
Unlock your iPhone or iPad, open the Camera app, and scan the QR code. Open the link that appears and follow the connection steps shown on the device.
### 3. Approve the connection
Keep the browser project open while the device connects. Approve any trust, install, or permission prompts required by the guided flow.
### 4. Run a focused test
Start with one complete journey. After a new build is ready, reconnect or refresh the device preview when Superapp asks you to do so.
## Superapp Web: test through TestFlight
Choose TestFlight when you need a signed beta that installs like a distributed app. Open the project’s publishing flow, connect the correct Apple Developer team, and submit a beta build. Apple processes the build before it becomes available in TestFlight.
1. Install Apple’s TestFlight app on the test device.
2. Accept the tester invitation with the Apple Account that received it.
3. Install the latest available build and confirm its version before testing.
4. Send the build number and a short test focus to every tester.
For team and external distribution details, continue to [Test with TestFlight](/testflight).
## Superapp for Mac: run through USB
### 1. Connect a data-capable cable
Connect the iPhone or iPad to your Mac, unlock it, and accept **Trust This Computer** if prompted. Some USB cables provide power but cannot transfer data.
### 2. Allow development on the device
Enable Developer Mode if iOS requests it, then restart and confirm the device prompts. Keep the device unlocked during the first connection.
### 3. Choose the physical device
In Superapp for Mac, open the run-destination dropdown that currently shows the Mac or a simulator. Select your connected iPhone or iPad instead.
### 4. Build and run
Start the app from Superapp. The first device build may take longer while Apple tooling prepares the device and resolves signing. Keep the cable connected until installation finishes.
## Superapp for Mac: use TestFlight
Mac projects can also create TestFlight builds. Use the same path when you want to test the signed distribution build, work without a cable, or invite other people. Direct USB testing and TestFlight complement each other; one does not replace the other.
## What to test on hardware
- First launch, relaunch, backgrounding, and interrupted tasks.
- Sign in with Apple, sign-out, and session restoration.
- Camera, photos, location, microphone, notifications, and denied permissions.
- Keyboard behavior, rotation, Dynamic Type, dark mode, and one-handed reach.
- Slow connections, offline recovery, battery use, and device temperature.
## If the device does not appear
Unlock the device, reconnect it, accept the trust prompt, and try a verified data cable or another USB port. Confirm that Developer Mode is enabled when required.
Keep the project page open, generate a fresh QR code, and scan it again. Check that both devices have a stable network connection and that the phone opens the complete connection link.
Confirm that Apple has finished processing the build, the tester has access to that version, and TestFlight is signed in with the invited Apple Account.
Verify the selected Apple Developer team, bundle identifier, device registration, and required capabilities. Then rebuild with the device unlocked and connected.
---
# Test with TestFlight
Source: https://superapp.dev/docs/testflight
TestFlight distributes beta versions through Apple’s infrastructure. It is the best place to validate installation, accounts, purchases, notifications, and real-device behavior before App Store review.
## Start with internal testers
Add trusted teammates first. Give each build a short test focus, such as onboarding or subscription restoration, instead of asking people to “test everything.”
## Expand to external testing
External testing may require a short Apple beta review. Include useful beta notes and make sure any required sign-in account works for the reviewer.
:::tip
A TestFlight build expires after Apple’s beta window. Upload a fresh build when testers can no longer open the previous one.
:::
---
# Start here: recover from an error
Source: https://superapp.dev/docs/troubleshooting
An error is easier to recover from when you stop changing the project and identify the first failing layer. Preserve the exact message, decide whether the issue is temporary or project-specific, and make one controlled recovery attempt.
## The first five minutes
1. Wait for any active Superapp change to finish.
2. Do not send the same request repeatedly or begin several unrelated fixes.
3. Copy the first meaningful error and note the action immediately before it.
4. Check whether the last working version still builds or previews.
5. Choose one matching guide below and test after one recovery change.
## Identify what is failing
Stop the loop and continue with [Escape an agent error loop](/agent-error-loops). Restate the observed error and ask for diagnosis before another edit.
Open [Fix Swift and Xcode build errors](/build-errors). Start with the first compiler error rather than the final “build failed” summary.
Use [Fix preview and runtime problems](/preview-runtime-errors) to separate an old preview, a launch crash, and incorrect app behavior.
Check [Fix signing and entitlement errors](/signing-entitlement-errors) before changing certificates or project identity.
Return to a previous working version. See [History and recovery](/history-and-recovery) before adding more repair prompts.
:::note
A retry is appropriate for a temporary timeout or unavailable service. The same deterministic compiler, configuration, or permission error will not improve by retrying unchanged.
:::
## If you need help
Follow [Collect diagnostics and contact support](/support-diagnostics). Include the project name, affected screen, steps to reproduce, and the exact error. Never include passwords, private keys, recovery codes, or service-role secrets.
---
# Evaluate your app idea
Source: https://superapp.dev/docs/validate-your-idea
An app earns attention by making a meaningful job easier for a particular group of people. Before building a large feature set, look for evidence that the problem is real, repeated, and important enough to change someone’s behavior.
## Begin with observed behavior
Personal experience is a useful starting point because you already know the vocabulary, awkward workarounds, and moments of frustration. It is not proof by itself. Talk to other people who face the same situation and watch what they do today.
- They spend time, money, or attention on a workaround.
- They can recall the last time the problem happened without being coached.
- They have tried another product and can explain why it falls short.
- They volunteer to test, introduce another user, or ask when it will be ready.
## Measure repetition and consequence
A problem can matter because it happens frequently, because each occurrence is painful, or both. Daily meal planning may be valuable through repetition; emergency coordination may be valuable through consequence. If neither is true, retention will be difficult.
### “I would probably try it.”
_Weak signal_
Interest is polite and costs nothing. It does not predict repeated use.
### “Can I use it for Friday?”
_Strong signal_
A specific moment and request suggest the person already feels the need.
## Picture the first user clearly
“Small businesses” is an audience category, not a product target. “Independent bakers who manage twenty to fifty weekly preorders through direct messages” is specific enough to find, interview, and design for. If you cannot name where the first five users come from, narrow the audience again.
## Watch for ideas that need scale before they work
Marketplaces, social networks, and broad all-purpose tools can appear simple while depending on a large user base, two-sided supply, or expensive distribution. They are not impossible, but a first version needs a useful experience even when only a handful of people have joined.
:::note
Ask: “What value does the very first active user receive?” If the answer depends on hundreds of other people, redesign the opening experience or choose a narrower problem.
:::
## Run a short validation sprint
### 1. Write the promise
Complete this sentence: “For this person, the app turns this difficult moment into this result.”
### 2. Interview five target users
Ask about the most recent occurrence, their current process, its cost, and what they have already tried. Avoid pitching until you understand the behavior.
### 3. Build one complete loop
Use Superapp to create the smallest version that delivers the promised result from start to finish. Leave accounts, sharing, and monetization out unless they are essential.
### 4. Observe unassisted use
Let testers attempt the task without a walkthrough. Record where they hesitate, whether they complete it, and whether they return when the problem happens again.
## Make a decision from evidence
Continue when users recognize the problem immediately, complete the core flow, and ask to use it in a real situation. Narrow or change direction when the value needs a long explanation, testers only praise the visuals, or nobody returns without a reminder.
:::tip
Set the pass condition before testing—for example, “At least three of five bakers use the prep plan for a real order week and ask to keep access.”
:::
---
# Choose web or Mac
Source: https://superapp.dev/docs/web-or-mac
Both versions let you create with AI. The web version removes local setup; the Mac app gives you a faster, more hands-on workflow with the native project on your computer.
### Start instantly
_Superapp Web_
Best when you want Superapp to manage the environment and get from idea to working app with minimal setup.
### Work locally
_Superapp for Mac_
Best when you want direct access to your project, Xcode, local tools, and a faster long-term iteration loop.
## Can I switch later?
Yes. Choose the simplest path for your current stage. Many builders start on the web and move to Mac when they want deeper control, local tooling, or a developer handoff.
---
# Website to native iOS app
Source: https://superapp.dev/docs/website-to-ios-app
Give Superapp the existing website as a reference and rebuild the experience for iPhone. Superapp does not place the site inside a WebView: it creates native SwiftUI screens, navigation, and device behavior.
## Choose what belongs in the app
A website and a mobile app should not contain exactly the same interface. Start with the actions people need while mobile—booking, tracking, ordering, messaging, scanning, or receiving updates—and leave long-form marketing pages on the web.
### 1. Share the source
Provide the public website URL and name the pages or flows that matter. If an important area requires sign-in, attach screenshots and describe the complete journey.
### 2. Explain the system behind it
Identify the backend, APIs, authentication, payments, CMS, and data ownership. A native interface still needs an approved way to read and update the same information.
### 3. Ask for a native product
Describe the mobile navigation, offline expectations, notifications, camera, location, Apple Pay, or other Apple capabilities that should improve the experience.
### 4. Validate feature parity
Compare outcomes rather than pixels. Confirm that users can complete the same important work and that account, inventory, subscription, or booking data remains consistent.
:::tip
A native rebuild can reduce the risk associated with thin website wrappers, but it must still provide meaningful app functionality and pass Apple's review.
:::
## Common website sources
- WordPress or Webflow content sites.
- Shopify or WooCommerce storefronts.
- Membership, booking, directory, or client portals.
- Lovable, Replit, Bolt, Bubble, or custom web applications.
---
# Prompt for better results
Source: https://superapp.dev/docs/write-better-prompts
Superapp makes stronger product decisions when it understands the person, the moment, and the outcome—not only a list of screens. A useful prompt sets direction while leaving room for the system to choose the right native implementation.
## Start with a compact product brief
Describe the app in one short paragraph before listing details. Name the target user, their situation, the task they need to complete, and what a successful session looks like.
```
Build an iPhone app for independent bakers preparing weekly orders.
The main job is turning confirmed orders into a calm, prioritized prep plan.
It should be fast to scan with flour-covered hands and require very little typing.
```
## Declare the priority and the boundaries
When speed, simplicity, visual character, and feature depth compete, tell Superapp which quality wins. Then remove tempting extras from the first build.
- **Primary goal:** “Optimize for a one-minute daily check-in.”
- **Scope:** “One main flow, three screens, no social features.”
- **Platform:** “Design for iPhone first and comfortable one-handed use.”
- **Quality bar:** “Prioritize clarity and finish over additional features.”
## Describe behavior, including edge cases
Explain what happens after a tap, what changes on screen, and what persists after the app closes. Include empty, loading, offline, permission-denied, and failed states when they matter. This turns a feature request into a testable interaction.
## Set a visual direction with useful references
Name two or three qualities such as quiet, energetic, editorial, dense, or playful. If you attach a reference, identify the specific lesson to take from it—navigation rhythm, typography, spacing, or motion—rather than asking for a copy.
### “Make it look premium.”
_Too vague_
The desired hierarchy, tone, and interaction quality remain undefined.
### “Quiet and precise.”
_Actionable_
Use generous spacing, restrained color, crisp type, and subtle feedback on taps.
## Ask motion to explain something
Motion should confirm an action, show where content came from, or preserve context during navigation. Request quick, subtle transitions and responsive pressed states. Avoid animation that slows a repeated task or competes with the content.
## Improve one outcome at a time
Test the current build, describe the observed behavior, and request one coherent change. A narrow follow-up is easier to verify and less likely to disrupt a working flow.
```
On the order detail screen, keep Mark as packed visible while scrolling.
After it is tapped, update the status immediately and keep it after relaunch.
Do not change the order list or navigation in this pass.
```
:::tip
The strongest prompt is not the longest. Give Superapp a clear outcome, enough context to make decisions, and boundaries that protect the current scope.
:::