Skip to main content

Nudges

Nudges are in-app messages displayed as bottom sheets or popups to guide users and drive actions.

Overview​

Raven Client supports multiple nudge types:

  • Bottom Sheets: Slide up from bottom (NUDGE_UI)
  • Popups: Modal dialogs (NUDGE_POPUP)

Bottom Sheet Nudges​

Bottom sheets slide up from the bottom of the screen:

{
  "actionId": "welcome-nudge",
  "type": "NUDGE_UI",
  "template": {
    "type": "BOTTOMSHEET",
    "props": {
      "title": "Welcome!",
      "message": "Thanks for using our app",
      "primaryButton": {
        "text": "Get Started",
        "action": {
          "type": "DEEPLINK",
          "url": "app://home"
        }
      }
    }
  }
}

Popup nudges appear as modal dialogs:

{
  "actionId": "update-popup",
  "type": "NUDGE_POPUP",
  "template": {
    "type": "POPUP",
    "props": {
      "title": "Update Available",
      "message": "A new version is available",
      "image": "https://example.com/update.png",
      "buttons": [
        {
          "text": "Update Now",
          "action": {
            "type": "DEEPLINK",
            "url": "app://update"
          }
        }
      ]
    }
  }
}

Nudge Components​

Title and Message​

{
  "title": "Welcome!",
  "message": "Get started with our app"
}

Buttons​

Primary Button​

{
  "primaryButton": {
    "text": "Get Started",
    "action": {
      "type": "DEEPLINK",
      "url": "app://home"
    }
  }
}

Secondary Button​

{
  "secondaryButton": {
    "text": "Maybe Later",
    "action": {
      "type": "DISMISS"
    }
  }
}

Images​

{
  "image": "https://example.com/image.png"
}

Lottie Animations​

{
  "lottie": {
    "source": "https://example.com/animation.json",
    "autoPlay": true,
    "loop": true
  }
}

Button Actions​

Navigate to a screen:

{
  "type": "DEEPLINK",
  "url": "app://home"
}

Event​

Trigger an analytics event:

{
  "type": "EVENT",
  "eventName": "BUTTON_CLICKED",
  "eventParams": [
    {"key": "buttonId", "value": "signup"}
  ]
}

Dismiss​

Dismiss the nudge:

{
  "type": "DISMISS"
}

Nudge Lifecycle​

Nudge Lifecycle

Required Setup​

Add Nudge Screen​

You must add the Nudge screen to your navigation stack:

import { Nudge } from '@dreamhorizonorg/raven-client';

<Stack.Screen
  name="Nudge"
  component={Nudge}
  options={{
    headerShown: false,
    presentation: 'transparentModal',
    animation: 'fade',
  }}
/>

Configure Route Name​

Set nudgeRouteName in SDK configuration:

nudgeClient.init({
  config: {
    nudgeRouteName: 'Nudge',  // Must match route name
    // ... other config
  },
});

Triggering Nudges​

Nudges are triggered automatically when:

  1. State machine reaches a state with a nudge action
  2. Action type is NUDGE_UI or NUDGE_POPUP
  3. CTA validation passes (frequency, expiration, etc.)

Examples​

For complete nudge examples with app integration, see:

Customization​

Styling​

Customize nudge appearance through template props:

{
  "template": {
    "type": "BOTTOMSHEET",
    "props": {
      "title": "Custom Nudge",
      "backgroundColor": "#FFFFFF",
      "titleColor": "#000000",
      "messageColor": "#666666"
    }
  }
}

Delay​

Add delay before showing nudge:

{
  "actionId": "delayed-nudge",
  "type": "NUDGE_UI",
  "config": {
    "triggerDelay": 2000  // Show after 2 seconds
  },
  "template": { /* ... */ }
}

Best Practices​

  1. Clear Messaging: Keep titles and messages concise
  2. Action Buttons: Always provide clear action buttons
  3. Frequency Control: Set frequency limits to avoid annoyance
  4. Contextual: Show nudges at relevant moments
  5. Test Thoroughly: Test nudges on different devices

Troubleshooting​

Nudge not showing​

  • Verify Nudge screen is added to navigation stack
  • Check nudgeRouteName matches route name
  • Ensure fetchCTA() is called after initialization
  • Verify CTA validation passes (frequency, expiration)

Nudge appearing on wrong screen​

  • Check navigation setup
  • Verify route name configuration
  • Ensure navigation ref is set correctly

Buttons not working​

  • Verify action types are correct
  • Check deep link URLs are valid
  • Ensure navigation is set up properly

Next Steps​