Capabilities

Capabilities are integration hooks that your website implements to expose additional functionality — for example, defining a function that handles adding a product to the shopping cart to enable an Add to Cart button inside a Fanplayr Product Recommendations widget.

Available Capabilities

Capability	Description
addProductToCart	"Add to Cart" button in Product Recommendations widgets
applyToCart	"Apply Offer" button in discount/offer widgets
sessionOffer	Notify your store when Fanplayr presents an offer to a visitor

Capabilities are registered on the fanplayr.platform.capabilities object inside the fanplayr_ready callback, which fires once the Fanplayr scripts have loaded.

window.fanplayr_ready = function () {
  // Register capabilities here
  window.fanplayr.platform.capabilities.addProductToCart = function (product) {
    /* ... */
  };
  window.fanplayr.platform.capabilities.applyToCart = function (event) {
    /* ... */
  };
  window.fanplayr.platform.capabilities.sessionOffer = function (event) {
    /* ... */
  };
};

---

Add Product to Cart

The addProductToCart capability allows Fanplayr's Product Recommendations widget to add a product directly to the visitor's cart without them leaving the page.

Handler signature

interface AddProductEvent {
  /** Product ID defined in the Fanplayr catalog */
  id: string
  /** Any custom data defined for the product */
  customData?: Record<string, any>
}

fanplayr.platform.capabilities.addProductToCart = (event: AddProductEvent) => void | Promise<void>

The handler receives an AddProductEvent object containing the product id from your Fanplayr catalog. Returning a Promise is supported — Fanplayr will wait for it to resolve before re-enabling the widget's button, which prevents duplicate submissions. Your handler is responsible for any additional cart parameters, such as quantity.

Basic example

Before you go live

This is an example only. You must replace the entire fetch call with your store's own cart API logic.

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.addProductToCart = function (product) {
    // Replace this with your store's actual cart API:
    return fetch('/api/cart/add', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ productId: product.id })
    });
  };
};

Using customData

If you define custom attributes on products in your Fanplayr catalog (e.g. variant IDs, SKUs, or internal references), they are available on product.customData and can be passed through to your cart API.

---

Apply Offer to Cart

The applyToCart capability allows Fanplayr's offer and discount widgets to apply a coupon or promo code directly to the visitor's cart.

Not the same as Add Product to Cart

This capability handles discount/offer codes (e.g. FREESHIP), not products. See Add Product to Cart if you want to integrate product recommendations.

There are two ways to implement this capability: a simple URL redirect approach, or a custom handler for more complex integrations.

Option 1 — URL redirect

Provide an applyToCartUrl as part of your user tracking configuration. Include the %c placeholder where the offer code should be inserted.

{
  type: 'st',
  accountKey: '7e43c8cddccade2b95ee5286ba89758a',
  applyToCartUrl: 'https://example.com/applyOffer.php?code=%c',
  data: {
    // User tracking data
  }
}

When a visitor activates the offer, Fanplayr redirects the browser to this URL with %c replaced by the offer code (e.g. FREESHIP), resulting in:

https://example.com/applyOffer.php?code=FREESHIP

Your endpoint must then:

1. Apply the specified offer code to the cart.
2. Redirect the user to the cart page.
3. Best practice: If the code cannot be applied, show an informative message explaining why.

Option 2 — Custom handler

If applying a code requires client-side logic (e.g. calling a JavaScript cart API), register a handler function instead.

Handler signature

interface AddOfferEvent {
  /** The offer/coupon code to apply */
  code: string
}

fanplayr.platform.capabilities.applyToCart = (event: AddOfferEvent) => void | Promise<void>

Basic example

Before you go live

This is an example only. You must replace the entire handler body with your store's own logic for applying an offer code.

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.applyToCart = function (event) {
    // Replace this with your store's logic to apply the offer code to the cart
    console.warn('Fanplayr: applyToCart capability is not implemented');
  };
};

Async example

Returning a Promise tells Fanplayr to wait for it to resolve before re-enabling the widget UI, preventing the handler from being triggered multiple times while your request is in flight.

Before you go live

This is an example only. You must replace the entire fetch call with your store's own cart API logic.

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.applyToCart = async function (event) {
    // Replace this with your store's actual cart API:
    await fetch('/api/apply-code-to-cart', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ code: event.code })
    });
  };
};

Legacy: completion callback

Earlier versions of this capability supported an optional doneFn callback as a second argument instead of a Promise. This is still supported for backwards compatibility, but the Promise approach above is preferred for new implementations.

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.applyToCart = function (event, doneFn) {
    $.ajax({
      type: 'GET',
      url: '/api/apply-code-to-cart',
      data: { code: event.code },
      complete: function () {
        doneFn();
      }
    });
  };
};

---

Session Offer

The sessionOffer capability is part of Fanplayr's Session Offers feature, which helps prevent unauthorized users from claiming discount codes outside of a Fanplayr session.

When Fanplayr presents an offer to a visitor, it invokes your sessionOffer handler with the offer code. Your handler is responsible for marking the code as valid for the duration of the visitor's session, so that your store can verify it before applying it to the cart.

URL-based alternative

If you prefer a server-side approach rather than a JavaScript handler, you can provide a sessionOfferUrl in your user tracking configuration instead. See Session Offers for full details.

Handler signature

interface SessionOfferEvent {
  /** The offer code being presented to the visitor */
  code: string
}

fanplayr.platform.capabilities.sessionOffer = (event: SessionOfferEvent) => void | Promise<void>

Returning a Promise is supported — if the Promise rejects, Fanplayr will treat the session offer as having failed and may retry on a later call. If the Promise resolves, or if no Promise is returned, the offer is considered successfully registered.

Example

Before you go live

This is an example only. You must replace the handler body with your store's own logic for marking an offer code as valid for the current session.

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.sessionOffer = async function (event) {
    // Replace this with your store's logic to mark the code as valid
    // for the current visitor session:
    await fetch('/api/session-offers/allow', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ code: event.code })
    });
  };
};