DSL Reference

AgentWallie's paywall schema includes a rich DSL (Domain-Specific Language) for conditionals, expressions, gradients, and animations. These features enable dynamic, personalized, and visually engaging paywalls without writing native code.

Conditionals

Conditionals control whether a component is rendered based on runtime data. Add a condition property to any component to gate its visibility.

Syntax

{
  "type": "text",
  "id": "trial_text",
  "props": { "content": "Start your free trial today" },
  "condition": {
    "field": "products.selected.has_trial",
    "operator": "is",
    "value": true
  }
}

Operators

Field Paths

Conditions can reference these field namespaces:

• products.* -- Product data: products.selected.has_trial, products.selected.price, products.primary.savings_percentage
• user.* -- User attributes set via SDK: user.plan, user.session_count, user.onboarding_complete
• device.* -- Device info: device.platform, device.session_count, device.locale
• theme.* -- Theme tokens: theme.primary, theme.background

Examples

Show a trial CTA only when the selected product has a trial:

{
  "type": "cta_button",
  "id": "trial_cta",
  "props": { "text": "Start Free Trial", "action": "purchase" },
  "condition": { "field": "products.selected.has_trial", "operator": "is", "value": true }
}

Show a special message for returning users:

{
  "type": "text",
  "id": "welcome_back",
  "props": { "content": "Welcome back! Here's a special offer.", "text_style": "headline" },
  "condition": { "field": "device.session_count", "operator": "gte", "value": 5 }
}

Expressions

Expressions use double-brace syntax ({{ }}) to insert dynamic values into text content, style values, and other string properties. Values are resolved at render time.

Syntax

{
  "type": "text",
  "id": "price_display",
  "props": {
    "content": "{{ products.selected.price }}/{{ products.selected.period }}"
  }
}

Available Variables

Examples in Text

{
  "props": {
    "content": "{{ products.selected.trial.period }} free, then {{ products.selected.price }}/{{ products.selected.period }}"
  }
}

Examples in CTA Buttons

{
  "type": "cta_button",
  "props": {
    "text": "Subscribe for {{ products.selected.price }}",
    "subtitle": "Save {{ products.primary.savings_percentage }}%"
  }
}

Complete Expression Path Reference

All available expression paths, their example resolved values, and descriptions:

Replace {slot} with a slot name defined in your schema (e.g., primary, secondary, tertiary). Replace {key} with any key defined in user attributes or the theme object.

Examples in Style Values

{
  "style": {
    "background_color": "{{ theme.primary }}",
    "corner_radius": "{{ theme.corner_radius }}"
  }
}

Gradients

Background gradients add visual depth to components. Use the background_gradient property inside style to apply a gradient behind component content.

Syntax

{
  "style": {
    "background_gradient": {
      "colors": ["#FF6B6B", "#4ECDC4"],
      "direction": "vertical"
    }
  }
}

Properties

Directions

Using Theme Colors

{
  "style": {
    "background_gradient": {
      "colors": ["{{ theme.primary }}", "{{ theme.secondary }}"],
      "direction": "horizontal"
    }
  }
}

Animations

Animations bring components to life when they appear on screen. Add an animation property to any component to animate its entrance.

Syntax

{
  "type": "text",
  "id": "title",
  "props": { "content": "Welcome" },
  "animation": {
    "type": "fade_in",
    "duration_ms": 300,
    "delay_ms": 100
  }
}

Properties

Animation Types

Shimmer Animation

The shimmer animation overlays a moving translucent gradient (transparent to white at 12% opacity to transparent) that sweeps horizontally across the element on a repeating loop. It is commonly used on CTA buttons to draw attention without being as aggressive as pulse.

{
  "animation": { "type": "shimmer", "duration_ms": 3000 }
}

Best Practices

• Use sparingly. Animate 2-3 key elements per paywall, not everything.
• Keep durations short. 200-500ms for entrance animations. Longer durations feel sluggish.
• Stagger with delays. Use incrementing delay_ms values (0, 200, 400) for sequential reveals.
• Match the purpose. fade_in for content, scale_up for CTAs, pulse for urgency.
• Don't animate legal links. Footer content should appear immediately.

Example: Staggered Reveal

[
  {
    "type": "text",
    "id": "title",
    "props": { "content": "Go Premium" },
    "animation": { "type": "fade_in", "duration_ms": 300 }
  },
  {
    "type": "feature_list",
    "id": "features",
    "props": { "items": [...] },
    "animation": { "type": "slide_up", "duration_ms": 400, "delay_ms": 200 }
  },
  {
    "type": "cta_button",
    "id": "cta",
    "props": { "text": "Subscribe Now" },
    "animation": { "type": "scale_up", "duration_ms": 300, "delay_ms": 500 }
  }
]

Additional Style Properties

glow_color

Adds a colored drop shadow beneath a component, creating a neon glow effect. Most commonly used on cta_button components. The SDK renders this as .shadow(color: glow_color, radius: 15, y: 4) on iOS.

{
  "style": {
    "background_color": "#ff0080",
    "glow_color": "#61FF0080"
  }
}

letter_spacing

Controls character tracking (spacing between letters). Commonly used on uppercase eyebrow labels or section headers for a wide, spaced-out appearance. The SDK applies .tracking(letterSpacing) on iOS.

{
  "style": {
    "letter_spacing": 4,
    "font_size": 11
  }
}

Paywall Settings Extensions

background_gradient

Apply a gradient background to the entire paywall view instead of a solid background_color. When both are set, the gradient takes precedence.

{
  "settings": {
    "background_gradient": {
      "colors": ["#06060f", "#1a0a20"],
      "direction": "vertical"
    }
  }
}

The gradient object uses the same format as component-level background_gradient in style (see Gradients above).

close_button_style

Controls how the close/dismiss button is rendered. Defaults to "icon".

{
  "settings": {
    "close_button": true,
    "close_button_style": "text"
  }
}

Next Steps

• Component Types -- All component types with props and examples
• iOS SDK - Custom Views -- Register native views for use in schemas