Metadata

Goal

These are the swipeable “welcome” panels a new user sees the very first time they open your app — the intro carousel. You’ll build the screens right here in WordPress, decide where each one shows up, control whether it comes back for returning users, and, if you like, connect it to the login hand-off and the location-permission prompt that often follow a first launch.

“Onboarding” means two different things

MAM Suite uses “onboarding” for two different things, and it’s easy to land on the wrong article — this one covers only the second.

Looking for the admin walkthrough that installs plugins and picks a home-screen layout? That’s the Setup Wizard article. Everything from here on is about what your app’s users see.

Prerequisites

• A working app with mam-main active and at least one user role configured.
• The MAM Onboarding add-on (mam-onboarding) installed and active. Without it, the onboarding settings described here do not appear, no onboarding payload is sent to the app, and the per-screen Help Content field stays hidden.
• At least one image in the Media Library for slide artwork — ideally sized for a full-screen slide.

How it works (the short version)

1. You create an Onboarding entry (a custom post of type mam-onboarding, labeled MAM Onboarding) and add one or more slides to it.
2. You attach that onboarding entry to a launch point — pre-login, post-login (per role), a specific screen’s Help Content, or a form.
3. On a phone-data request, mam-main and mam-onboarding build a panel payload — the bundle of slide data sent to the app — from your slides and include it in the app’s JSON response.
4. The mobile client renders the panels as a swipeable carousel and shows it at the configured launch point.
5. A cursor — a saved marker of what a user has already seen — decides whether they see the carousel again. Change the cursor and everyone gets it once more.

App launch (no auth state)
        │
        ▼
Pre-login onboarding carousel renders (welcome screens)
        │
        ▼
User taps through to the login / registration screen
        │
        ▼
Signs in → (optional) post-login onboarding for their role
        │
        ▼
Next launch: cursor unchanged → carousel is skipped, home screen shows

Step 1 — Build the onboarding screens

Mobile App Manager → Onboarding Manager → Add New (the MAM Onboarding post type).

1. Give the onboarding entry a title (admin-only label, e.g. “First Launch Welcome”).
2. In the App Slides panel, add one slide per intro screen. Each slide is a full screen in the carousel, built from stacked content sections — typically an image, a heading, body text, and spacers — each with its own color, font size, and dimensions.
   • Image — a full-screen graphic (a product shot, an illustration, or your brand art).
   • Title — a short headline.
   • Body — one or two sentences explaining the value of that screen.
3. Add a slide per idea you want to land before sign-up — typically three to five. Keep the copy short; users swipe through quickly.
4. Reorder slides as needed; the order is the swipe order in the app.
5. Publish.

All of your slides go out to the app in one data response, and the mobile client handles the paging — you’re building the whole deck at once here, not “one slide per launch.” Behind the scenes, each published onboarding entry becomes a stacked-panel structure: every slide turns into one panel with swipe-forward, swipe-back, and skip already enabled, and its hex colors get converted to RGB for the mobile client. None of that is anything you need to touch.

Step 2 — Choose where the onboarding appears

MAM Onboarding can appear at several different points in the app’s journey — pick the one that matches what you’re trying to do.

A. Pre-login onboarding (before the user signs in)

This is the one everyone knows — the classic “welcome to the app” intro, shown to anyone who opens the app while signed out, right before the login/registration screen.

It’s controlled by a pre-login onboarding selection: set it, and the app payload includes a pre_login_onboarding block (plus a pre_login_onboarding_cursor). Pick your published onboarding entry as the pre-login course in the onboarding settings.

B. Post-login onboarding (per user role)

Shown right after a user signs in. This one is role-aware — assign a different onboarding entry to each role, or use a single entry for everyone. Set it, and the payload includes an onboarding block (plus an onboarding_cursor).

Assign your onboarding entry to the relevant role(s) in the onboarding settings.

C. Per-screen Help Content

Any app screen that has a Help Content setting can point at an onboarding entry, too — it renders the same carousel, but as contextual help for that one screen instead of at launch.

In Mobile App Manager → App Settings for the screen/button, set the Help Content field (internal key screen_help) to your onboarding entry. mam-main resolves that ID through the onboarding builder (mam_lp_create_onboarding::create_onboarding()) and embeds the panels in that screen’s data. The field only appears when the onboarding manager (or LearnPress) class is loaded.

D. Form help screens

Forms can carry their own onboarding entry too, as a help overlay keyed per form (stored as the mam-onboarding-{form_id} option) — it surfaces under a help_screens block in the payload. Reach for this when you want to walk users through a specific form the first time they open it.

Step 3 — Control when onboarding reappears

By default, the mobile client shows onboarding once, remembers that it did, and leaves returning users alone. What controls that memory is the cursor:

• Each onboarding course stores a cursor value (a unique string).
• The app compares the cursor it last saw against the one in the payload. If they differ, it shows the carousel again; if they match, it skips it.
• Re-showing onboarding to everyone: change/reset the cursor for that course. The next launch presents the carousel once more, then quietly remembers it again.

This is the supported way to “re-run” an updated welcome flow after you revise your slides — bump the cursor so existing users see the new version.

Step 4 — Optional: an Onboarding button or home-screen action

Two extras let users — or you — reopen onboarding whenever it’s useful:

• Onboarding nav button. mam-main ships an Onboarding content class (local_app_onboarding) — a navigation button with one job: launch the onboarding flow. It has no settings of its own (“No settings required”) — its slides come from whatever onboarding entry you wired up in Step 2. Add it from Mobile App Manager → Buttons if you’d like a left-menu or tab entry that replays the intro.
• “Open Onboarding” home-screen action. When you’re composing a home screen, the home-screen stack offers an Open Onboarding action (open_onboarding) you can attach to any tile or button, so users can revisit the intro right from the home screen.

Step 5 — Optional: the login hand-off and location prompt

A first launch usually flows straight into sign-up and, for GPS apps, into a location request right after that. Two small adjustments turn that hand-off into one continuous moment instead of a series of separate screens.

Style the login / sign-up screen

The login and sign-up screens are styled separately under the Login settings — background image (login_background_url_1) and color, logo, button titles, and the terms-and-conditions text (login_terms_and_conditions_text) and URL (terms_and_conditions_url). Match the login background art to your closing onboarding slide so the transition from carousel to sign-up looks continuous.

Location-permission prompt (only if your app uses GPS)

If any screen in your app needs location — a map, geofilters, nearby listings — put an Enable Location Services button (mam-main‘s open_location_services content class, content type “Enable Location Services”) somewhere in the path toward that feature. Like the Onboarding button, it has no settings of its own (“No settings required”) — tapping it prompts the user to enable location, or opens the device’s location settings directly.

That dialog’s wording, though, isn’t set on the button itself — it comes from the iOS GPS permission string at Mobile App Manager → Publish Your App → Permission strings (ios_app_gps_message). Apple and Google reviewers read this copy closely, and a vague or empty string can get a build rejected, so spell out plainly why your app needs location. One thing worth knowing going in: the OS prompt is one-shot — if the user declines, the app can’t ask again, and they’ll need to re-enable location in device Settings themselves.

If nothing in your app needs location, skip this entirely.

Verification

• On a fresh install of the Previewer (clear app data, signed out), the pre-login carousel appears before the login screen and swipes through all slides.
• Tapping through the carousel lands on the correct registration/login screen, and its background matches your slide art.
• After signing in as a user in a role with onboarding assigned, the post-login carousel appears once.
• Relaunching the app does not re-show the carousel (cursor unchanged).
• After resetting the cursor, the next launch shows the carousel again exactly once.
• A screen with Help Content set displays the same panels as contextual help.
• If you added an Enable Location Services button, walking to the GPS feature triggers the OS location prompt with your ios_app_gps_message copy.

Troubleshooting

Related articles

• Setup Wizard (site onboarding for admins)
• Content classes overview
• Recipe: Customer enrollment and account code
• Building a home screen with the home-screen stack
• Recipe: Publish your app to iOS and Android (where the OS permission strings live)
• App setting: Login → background image / Terms and conditions text and URL
• Hook: mam_onboarding_create_onboarding_panel (customize a generated panel)
• Hook: mam_onboarding_add_help_screens (inject or alter form help screens)
• Hook: mam_get_phone_data_before_send (where onboarding payload is assembled)

Verification sources

• mam-main/includes/content-classes/local-app-onboarding-content-class.php — the Onboarding nav-button content class (local_app_onboarding; no settings; launches the flow).
• mam-main/includes/content-classes/local-app-enable-location-services-content-class.php — the Enable Location Services nav-button content class (open_location_services; no settings; prompts/opens device location).
• mam-main/includes/content-classes/README.md (L26) — Onboarding listed as “Onboarding” / “First-launch onboarding screens.”
• mam-main/includes/app-settings/admin-settings-page.php (~L2032–2040) — the Help Content setting (screen_help, type learnpress), gated on tsl_mam_learnpress / mam_onboarding_manager.
• mam-main/includes/app-settings/local-settings.php (~L315–327) — screen_help resolved via mam_lp_create_onboarding::create_onboarding(); adjacent (~L329–345) login_terms_and_conditions_text and login_background_url_1 handling.
• mam-main/includes/forms-manager/forms-manager-main.php (L409–411) — per-form onboarding stored as the mam-onboarding-{form_id} option.
• mam-main/includes/helper-classes/home-screen-stack-manager.php (~L342) — Open Onboarding home-screen action (open_onboarding).
• mam-main/includes/publish-app/mam-app-publishing.php (L28) and publish-app/README.md (L27) — ios_app_gps_message permission string.
• mam-onboarding add-on (not present in this checkout): the CPT registration, “App Slides” metabox (_mam_lp_slides), mam_lp_create_onboarding::create_onboarding() panel builder (hex→RGB), and the pre_login_onboarding / onboarding / help_screens + cursor assembly. Re-verify these against the shipping add-on.

Re-verify if the onboarding builder add-on is renamed or relocated, the slide meta key or panel shape changes, the cursor/reset UI changes, or the launch-point options (pre-login / per-role / help / form) are reorganized.
</content>
</invoke>