Skip to content

App Store

Setting up and managing the Tomoda iOS app through App Store Connect (ASC). Binaries are built locally and uploaded by hand (see Native Release); this page covers everything else ASC requires: Apple Developer account, app record, signing, TestFlight, App Privacy, App Review, post-launch operations.

If you're shipping a code change, you don't need to touch this page: task native:beta:ios builds and uploads to TestFlight in one step (fastlane pilot). Read this page when you're setting up the app for the first time, managing TestFlight groups, updating App Store metadata, or navigating App Review.

1. Apple Developer Program

Mandatory for distributing any iOS app.

  • Cost: US$99/year.
  • Sign-up: https://developer.apple.com/programs/enroll/.
  • Account type: Choose Organization (requires a D-U-N-S number — Apple provides a lookup tool during signup). Personal accounts can't publish under a company name.
  • Identity verification:
    • D-U-N-S number for the legal entity (free; takes ~1 week if your company isn't already listed)
    • Legal-entity contact information matching the D-U-N-S record
    • Apple typically reviews enrollment within 24–48h once D-U-N-S clears
  • Renewal: annual. Don't let it lapse — the app is removed from the store within days of expiration.

The signed-up Apple ID becomes the Account Holder. Add team members as you onboard engineers/designers (Account Holder → Users and Access → Add user).

2. App Store Connect — create the app record

Once enrolled in the Developer Program:

  • ASC → My Apps → New App
  • Platforms: iOS
  • Name: Tomoda
  • Primary language: English (U.S.)
  • Bundle ID: com.tomoda.app (must exist in Certificates, Identifiers & Profiles first; register it in the Apple Developer portal, or let Xcode create it the first time you build)
  • SKU: internal identifier, never shown to users (tomoda-ios works)
  • User access: Full Access by default

This creates the app record and a numeric ASC App ID. For Tomoda this is 6765908734; you'll need it when uploading a build to this record.

3. Signing & certificates

Apple's signing infrastructure is the complex part of iOS distribution. Tomoda signs manually through Xcode and the Apple Developer portal for Apple Team 33TV825K7S.

What you manage

  • iOS Distribution Certificate — proves builds come from Tomoda's Apple Developer team
  • App Store Provisioning Profile — pairs the certificate to the bundle ID com.tomoda.app for App Store distribution
  • Push notification certificates — generated when push support is added; not in scope today

Signing is shared via fastlane match (see Signing): the distribution cert + App Store provisioning profile live encrypted in a private GCS bucket, and task native:beta:ios signs manually with that identity on any machine, so you never configure signing in Xcode. Team 33TV825K7S.

An ASC API key lets you upload builds non-interactively (via xcrun altool / xcrun notarytool) without your full Apple ID password:

  1. ASC → Users and Access → Keys → +
  2. Name: something recognizable (e.g. "Upload key")
  3. Access: App Manager (enough to upload builds without admin rights)
  4. Download the .p8 file (one-time download — Apple does not let you re-download).
  5. Note the Key ID and Issuer ID shown after creation.

Store the distribution certificate .p12, its private key, the provisioning profile, and the API key .p8 in your team password manager. Losing the distribution certificate's private key means regenerating the cert and profile.

Push notification certs revoke distribution certs

Apple's UI buries this — generating a new distribution certificate without revoking the old one is fine, but revoking a distribution certificate immediately invalidates every provisioning profile signed with it, which means any app shipped with that profile breaks on next launch. Read carefully before revoking anything in Certificates, Identifiers & Profiles.

4. App Store listing

Required before any public release. Required for TestFlight external testing too (internal is exempt).

Required text

Field Limit Notes
Name 30 chars "Tomoda"
Subtitle 30 chars One-line elevator pitch — e.g. "Find friends through shared moments"
Promotional text 170 chars Above-the-fold blurb (can be updated without re-review)
Description 4000 chars Marketing copy. Markdown not supported — plain text with line breaks.
Keywords 100 chars total (comma-separated) Affects search ranking. Don't repeat words from the title — wasted space.
Support URL URL https://tomoda.life/help (public help center with the support email)
Marketing URL URL (optional) Product landing page
Privacy Policy URL URL — required Must be live and resolve to a real privacy policy

Required graphics

Asset Spec Notes
App icon 1024×1024 PNG, no transparency, no rounded corners Apple rounds it. Don't pre-round.
6.7" iPhone screenshots 1290×2796 (portrait) 3–10 images required
6.5" iPhone screenshots 1242×2688 or 1284×2778 3–10 required if you support iPhone X-class displays
(Optional) 5.5" iPhone, iPad older devices Skip unless you specifically support them
(Optional) App Preview videos 15–30s, .mov/.m4v High-effort, big lift in conversion

Apple no longer enforces uploading every device-size variant — you can scale a single screenshot set up to all devices in ASC. But the 6.7" set is mandatory.

Category and age rating

  • Primary category: Social Networking
  • Secondary category: Lifestyle (optional; helps surface in browse)
  • Age rating: 18+, to match the Terms, which require members to be 18. Answer the questionnaire under App Information → Age Rating truthfully (user-generated content, messaging, unrestricted web access via link previews), then raise the result to 18+ with the higher-rating option at the end of the questionnaire.

5. App Privacy

Under App Privacy (a separate ASC section, mandatory). Walk through the questionnaire — Apple's labels appear on the App Store listing and are scrutinized.

The answers live in one place: legal/app-store-data-mapping.md in the operations repo (private). It is reconciled against this repo's code and compliance/surface.json, so fill the questionnaire from it rather than from memory, and change it there first when a data type changes.

"Tracking" in Apple's sense means tracking the user across other apps/websites for advertising. Tomoda has no tracking SDK and sends no advertising identifier, so every type answers No for tracking. The GIF picker shows ads from the GIF provider: ad content is web content fetched through our backend, and the app sends device model, OS version, screen size and language for it, so the device data types are used for third-party advertising (see the operations data mapping).

The binary also carries an on-device privacy manifest (PrivacyInfo.xcprivacy), generated at prebuild from ios.privacyManifests in frontend/app.config.js. It declares no tracking, the required-reason API categories the app target needs (user defaults, file timestamp, system boot time, disk space; pod manifests are aggregated by Xcode on top), and the collected data types. Keep the collected data types in sync with the App Privacy answers: when a label changes, update both, and __tests__/config/privacyManifest.test.ts guards the keys. Add a required-reason category there when a new native dependency uses one.

6. TestFlight

Apple's beta distribution channel. Two flavors:

Type Audience Approval needed
Internal testing Up to 100 testers with Apple ID + ASC role No review — instant availability
External testing Up to 10,000 testers First build per version requires beta review (typically 24h)

Internal testers must be added as users in ASC → Users and Access first. They install TestFlight from the App Store, sign in with the same Apple ID, and the build appears.

External testers can be invited by email or by a public link. They don't need an ASC account. Each cohort can be configured separately (e.g. "Designers", "Friends and family", "Public Beta").

Set up your first internal group before the first build upload so the build has somewhere to land.

7. App Review

Apple reviews every release before it goes to the App Store. Plan for:

  • Time: typically 24–48h. First submission can take longer; complex reviews (financial flows, health data, kids' apps) longer still.
  • Common rejection reasons:
    • Guideline 4.0 — Design: copying iOS UI patterns inconsistently (e.g. custom share sheet that looks like the system one but behaves differently)
    • Guideline 5.1.1 — Data Collection and Storage: privacy disclosure mismatch with what the app actually does
    • Guideline 1.1.6 — False Information: claims in the description that don't match the app's behavior
    • Sign in with Apple required: if you offer third-party login (Google, etc.), you must also offer Sign in with Apple, prominently
    • Crashes during review: if review can't get past a sign-up flow, the app gets rejected — keep the demo account credentials populated in App Review Information
  • Demo account: required in App Review Information for any app behind a login. Use a test account dedicated to App Review, not a real user account. Tomoda's is the seeded review account: fill Sign-in required with the user name review@tomoda.life and the password from the Secret Manager secret tomoda-review-account-password (gcloud secrets versions access latest --secret=tomoda-review-account-password, project development-485000). Put in the Notes field that the account signs in with email and password, needs no one-time code, and comes with sample friends, a plan, an event and a chat. Update the field after a rotation.

Speeding up review

  • Submit during weekdays, US morning Pacific time.
  • Request expedited review only for security fixes or actual production incidents. Apple grants ~1–2/year per developer; spend them carefully.
  • Pre-empt rejections by reading the most recent guidelines update before submitting.

8. Upload the build

The lanes build and upload in one step (fastlane pilot); see Native Release:

task native:prod:ios      # prod .ipa (frontend/build/ios/ipa/) -> TestFlight, recorded for release
task native:release:ios   # submit that build for App Store review

ASC processes the build (~5 to 30 min) and makes it available in TestFlight. Add it to your internal group, vet it on a device, then run the release task (or select the build under App Store → Prepare for Submission and submit by hand).

The build moves from TestFlight to a "Waiting for Review" state. Approved builds release on the next manual "Release this version" tap (or scheduled date).

9. Post-release operations

  • Crash reports: ASC → Analytics → Crashes shows crashes for users who opted in (~70% of users). Symbolicated automatically when dSYMs are uploaded — the local build uploads them to Sentry via build-with-secrets.sh, and Xcode/altool includes them in the App Store upload.
  • App Store ratings & reviews: respond promptly. Apple's "developer response" feature is public.
  • Phased release: new releases roll out over 7 days by default. Toggle in ASC if you want immediate full release (small fixes) or want to halt rollout (regression detected).
  • App removal: if you ever need to pull the app, ASC → "Remove from Sale" instantly hides from the store. Existing installs are unaffected.

10. Useful references

See also