@mindful-web/marko-web-mindful-ads

Marko components for serving Mindful ads on Mindful Web websites.

Requirements

Environment variables

| Variable | Required | Description | |---|---|---| | MINDFUL_AD_SERVER_DATA_API_KEY | Yes | API key for the Mindful ad server data API. The application will fail to start without this set. | | MINDFUL_AD_SERVER_URL_SERVER | No | Server-side ad server base URL. Defaults to https://serve.mindfulcms.com/ads. | | MINDFUL_AD_SERVER_URL_BROWSER | No | Browser-side ad server base URL used by the init component. Defaults to https://serve.mindfulcms.com/ads. |

Middleware

The p1EventsVisitorCookie middleware from @mindful-web/marko-web-p1-events must be registered before ad components can serve ads. This middleware sets the visitor tracking cookie that the ad server uses to correlate requests.

const { p1EventsVisitorCookie } = require('@mindful-web/marko-web-p1-events/middleware');

app.use(p1EventsVisitorCookie());

Usage

Initialization

Add the <marko-web-mindful-ads-init> component once in your page layout to bootstrap the browser-side ad library. The component must be rendered somewhere before the closing </@head> tag. Pass the Mindful tenant key (the org portion of your namespace, e.g. lbm).

<marko-web-mindful-ads-init tenant="lbm" />

Rendering an ad unit

Use <marko-web-mindful-ads-website-banner> to request and render a banner ad. The namespace corresponds to your Mindful workspace (e.g. lbm/default).

<marko-web-mindful-ads-website-banner
  namespace="lbm/default"
  adUnitId="1234abcde1234"
  siteId=config.website('id')
/>

| Attribute | Type | Required | Description | |---|---|---|---| | namespace | string | Yes | Mindful workspace namespace, e.g. lbm/default. | | adUnitId | string | Yes | The Mindful ad unit ID to request. | | siteId | string | Yes | The Mindful website ID. | | advertiserIds | string[] | No | Restrict results to specific advertiser IDs. | | limit | number | No | Maximum number of creatives to return. Defaults to 1. | | sizes | string[] | No | Filter by creative sizes. | | debug | boolean | No | Enable debug logging. |