BadgerFy.ai Docs

Nudge Agent

The Nudge Agent simplifies the creation of intelligent, contextual pop-ups or banners that display on your website pages. These nudges can provide insights into product recommendations, discounts, and new features, all based on your dataset using AI. This eliminates the need to configure them individually for each page. Additionally, nudges can be set up manually without AI to provide a precise, static message when needed.

Overview

Nudges are designed to proactively engage customers, guiding them towards desired actions or informing them about relevant offers based on their browsing context.

Data Source Instructions

The Nudge Agent works best with a Product & Promotions data source, which contains structured product and promotion data. See the Product & Promotions Data Documentation for format details.

Tips for Nudge Data Sources

  • Page Path Matching: Include productPath in your dataset that matches the page URLs where nudges should appear.
  • Promotion Text: If your data includes a promotionText field, the nudge will display that text directly without using AI generation—saving tokens and ensuring consistency.
  • CTA Links: Include a ctaLink field in your promotions to specify where the CTA button should link. If no link is in the dataset, the default CTA link from your nudge rule will be used (or the CTA will be hidden if no default is set).
  • Metadata Fields: Use the metadata object on products and promotions to include additional context that the AI can reference when generating nudge messages.

Content Customization

The Nudge Agent offers various options for content and behavioral customization:

  • Message: When AI is enabled, the nudge message is generated from your data. If your dataset includes promotionText, that text is used directly (no AI tokens consumed). Otherwise, AI generates a concise 72-character message.
  • CTA Button: Optionally include a call-to-action button with custom text. The link comes from your dataset's ctaLink field, or falls back to a default link you specify in the nudge rule.
  • Trigger Delay: Set a delay (in seconds) before the nudge appears on the page.
  • Visibility Period: Configure how long the nudge remains visible on the screen (in seconds). A value of 0 means it stays visible until dismissed.
  • Positioning: Choose where the nudge appears on the screen (e.g., bottom-right, top-center).
  • Static Mode: Disable AI to provide a fixed message for precise control over the nudge content.

Page Path Matching

Nudge rules are matched against page URLs using a priority-based system:

  • Exact Matches: Rules with exact path matches are prioritized first (e.g., /products/wireless-headphones).
  • Wildcard Patterns: Use * for flexible matching (e.g., /products/* matches all product pages). More specific patterns take priority over generic ones.
  • Query Parameters: The system intelligently matches URLs with query parameters, preferring records with the most matching parameters (e.g., /products/shirt?color=blue&size=M).
  • Random Selection: When multiple rules match with equal specificity, one is selected randomly—adding natural variety to your nudges.

Multiple Promotions Per Product

Products can have multiple promotions in your dataset. When a nudge is triggered, one promotion is randomly selected from the available options. This creates variety for returning visitors and allows you to A/B test different promotional messages naturally.

Rate Limiting & User Experience

To prevent nudge fatigue and maintain a positive user experience, the Nudge Agent includes built-in rate limiting:

  • Page Cooldown: After a nudge is displayed on a page, that same page won't show another nudge for 1 hour. This prevents visitors from being overwhelmed by repeated nudges on the same page.
  • Session-Based: The cooldown is stored in the visitor's browser (localStorage), so it persists across page refreshes but resets after the 1-hour window.
  • Test Mode Bypass: When using the data-force-agent-id attribute or the dashboard test page, cooldowns are bypassed to allow for rapid testing.

Token Efficiency & Caching

The Nudge Agent is designed to minimize token usage and API costs:

  • Direct Text Mode: If promotionText exists in your dataset, it's used directly—no AI generation, no tokens consumed.
  • Server-Side Caching: AI-generated nudges are cached for 1 hour on our servers. Repeated requests for the same page path return the cached result instantly without consuming tokens.
  • Client-Side Cooldown: The 1-hour page cooldown also reduces API calls by preventing repeated nudge requests on the same page.
  • No AI for CTAs: CTA links and text always come from your dataset or rule configuration, never from AI generation.

Styling

The Nudge Agent can be customized with extensive styling options:

  • Theme: Choose between light and dark color themes as a starting point.
  • Container: Customize background color, border color, border radius, and drop shadow.
  • Typography: Choose from system fonts (sans-serif, serif) or specify a custom font family that matches your brand.
  • Content: Style the message text color, font size, and close button color.
  • CTA Button: Customize button background, text color, font size, and border radius.

All styling is done through the intuitive WYSIWYG editor in your dashboard. For advanced customization, you can add global CSS rules to target the nudge's specific CSS classes.

Analytics

BadgerFy.ai tracks various metrics related to your nudge's usage, including nudge displays, CTA click-throughs, and token consumption (for AI-generated nudges). You can also download a history of nudge generations for analysis.