Goal

Customize the first-launch onboarding screens shown to new app users, the welcome email they receive on registration, and the profile completion flow that follows.

Prerequisites

• An app with at least one configured user role
• The Onboarding content class enabled (default)
• Optional: Gravity Forms for a programmatic profile-completion form

Two distinct concepts

The word “onboarding” covers two separate things in mam-main:

This recipe covers app-user onboarding. For site onboarding, see Recipe: Customer enrollment and account code.

Steps

1. Configure the Onboarding content class

The Onboarding button is one of the 21 content classes (local-app-onboarding-content-class.php). It renders a carousel of intro screens shown on first app launch.

Mobile App Manager → Buttons → add an Onboarding button (or edit the default one). Per-button settings cover:

• The carousel slides (image + title + body per slide)
• The CTA (typically “Sign up” or “Log in”)
• Whether to show the carousel for returning users (off by default)

See Content class: Onboarding.

2. Configure the welcome email

When a user registers, mam-main fires do_action('mam_notification_send_message', ['message_type' => 'mam-user-roles-welcome_email', ...]). The dispatcher resolves the type from the mam_notification_list registry and sends through enabled channels.

Edit the template in Mobile App Manager → Notifications → Settings → User Roles – Welcome Email:

• Subject line
• Email body (with replacement tokens: [user_login], [user_email], [display_name], [first_name], [last_name], etc.)
• Per-channel toggles (email is on by default; SMS/push are off unless explicitly enabled)

Available replacements: ID, user_login, user_nicename, user_email, user_url, user_registered, display_name, first_name, last_name, nickname, description.

See Notification types registry.

3. Configure the profile completion form

After registration, prompt the user to fill out their profile. Build a Gravity Forms form, then bind it to the profile-completion flow:

1. Build the form in Forms → Add New
2. In Mobile App Manager → Forms, configure the per-field special handling
3. Add additional profile fields by hooking mam_add_fields_to_user_profile
4. Per-field save logic uses the dynamic hook mam_user_roles_save_addl_user_profile_field_{key} — see Hook: mam_user_roles_save_addl_user_profilefield{key}

4. (Optional) Use the AI assistant

MAM_AI_Admin (includes/setup-wizard/mam-ai-assistant.php) helps customer admins draft onboarding copy, slide titles, and notification templates. It surfaces in the wizard as suggested defaults you can accept or edit.

How the first-launch flow works

App launch (no auth state)
        │
        ▼
   Phone-data request
        │
        ▼
   Pipeline phase_content
        │
        ▼
   Onboarding content class fires get_data_for_app()
        │
        ▼
   Renders the carousel slides
        │
        ▼
   User taps Sign up → Registration form opens
        │
        ▼
   Submission → do_action('mam_notification_send_message', welcome_email)
        │
        ▼
   User logged in → next phone-data request returns the home-screen
   stack instead of onboarding (Onboarding class checks `is_returning_user()`)

For users with a pending invite (caregiver invitation, staff invitation, claim invitation), some sibling plugins inject a different first-launch flow via inject_pending_invite_form() — see, for example, mam-geodirectory’s mam_geodirectory_phone_data integration.

Hooks involved

Verification

• Fresh install of the Previewer (clear app data) shows the onboarding carousel
• Registration produces a welcome email landing in the user’s inbox
• A second app launch (now logged in) skips the carousel and shows the home screen
• Profile-completion form, if configured, renders the extra fields injected by mam_add_fields_to_user_profile

Related articles

• Recipe: Build an app end-to-end
• Recipe: Customer enrollment and account code
• Content class: Onboarding
• Notifications overview
• Hook: mam_add_fields_to_user_profile
• Hook: mam_user_roles_after_create_user
• Hook: mam_user_roles_save_addl_user_profilefield{key}
• Hook: mam_user_logged_in
• Hook: mam_notification_send_message

Metadata