Declarative Tracking

Declarative tracking lets you track simple website interactions by adding data-vendo-* attributes to HTML elements. Use it for straightforward UI events where the event name and properties are already available in the page markup.

For application state, confirmed purchases, backend outcomes, or anything that depends on business logic, use the imperative JavaScript methods such as vendo.track() and vendo.identify().

When To Use Declarative Tracking

Use declarative tracking for:

• CTA clicks
• Navigation clicks
• Form submits
• Product card clicks
• Newsletter signups
• Section impressions when an element becomes visible

Use imperative tracking for:

• Completed checkouts
• Subscription changes
• Login or signup completion
• API-driven state changes
• Events where properties come from application state rather than the DOM

Both approaches send normal Vendo track events and receive the same automatic context, including page URL, referrer, session ID, anonymous ID, UTM parameters, and click IDs.

Declarative attributes only define the event name, trigger, and event-specific properties. The SDK still adds context from the page URL, browser, screen, localStorage-backed IDs and attribution, and supported cookies such as Meta’s _fbc cookie.

Basic Click Event

Add data-vendo-track to an element. Click is the default trigger.

<button
  data-vendo-track="Product Added"
  data-vendo-product-id="prod_123"
  data-vendo-product-name="Linen Shirt"
  data-vendo-price="89.00"
>
  Add to cart
</button>

When the visitor clicks the button, Vendo sends:

vendo.track('Product Added', {
  product_id: 'prod_123',
  product_name: 'Linen Shirt',
  price: '89.00',
});

Any data-vendo-* attribute becomes an event property, except:

Attribute names are converted from kebab case to snake case. For example, data-vendo-product-id becomes product_id.

Supported Triggers

Form Submit

<form
  data-vendo-track="Newsletter Signup Submitted"
  data-vendo-trigger="submit"
  data-vendo-placement="footer"
>
  <input type="email" name="email" />
  <button type="submit">Subscribe</button>
</form>

Visible Impression

<section
  data-vendo-track="Pricing Section Viewed"
  data-vendo-trigger="visible"
  data-vendo-section="pricing"
>
  ...
</section>

The visible trigger fires once per element after the element reaches the visibility threshold.

Declarative And Imperative Together

You can use both approaches on the same site.

Declarative tracking is best for simple UI interactions:

<a
  href="/contact-sales"
  data-vendo-track="Contact Sales Clicked"
  data-vendo-placement="header"
>
  Contact sales
</a>

Imperative tracking is best when the event depends on app logic:

await completeCheckout(order);
 
vendo.track('Checkout Completed', {
  order_id: order.id,
  revenue: order.total,
  currency: order.currency,
});

Avoid tracking the same business event in both places unless you intentionally want two different events. For example, track Checkout Button Clicked declaratively and Checkout Completed imperatively after the order succeeds.

Naming Guidance

Use event names that describe what happened:

• Product Viewed
• Product Added
• Checkout Started
• Checkout Completed
• Newsletter Signup Submitted
• Contact Sales Clicked

Use properties for details about the event:

<button
  data-vendo-track="Plan Selected"
  data-vendo-plan-id="growth"
  data-vendo-billing-interval="monthly"
  data-vendo-placement="pricing_table"
>
  Choose Growth
</button>

This keeps the event name stable while properties capture the specific plan, placement, product, or campaign.

Verify Events

1. Temporarily initialize the SDK with debug: true.
2. Open your browser’s Network tab.
3. Interact with the tracked element.
4. Look for a request to /collect.
5. Confirm the payload includes your event name, data-vendo-* properties, and the automatic context object.
6. Check live events or your warehouse destination to confirm delivery.

If the event does not send, confirm the SDK snippet is loaded before the interaction and that the element includes data-vendo-track.