README

AdAlong Widget library

Getting Started

Browser compatibility

This package doesn't support internet explorer.

Installation

Via NPM

Install the plugin with NPM

npm i @adalong/widget

Then you can import it in your code

import AdalongWidget from '@adalong/widget'

Via CDN

Add the CDN url directly in your HTML code to make it available globally. Ensure to replace [VERSION] with the right version.

<script src="https://cdn.jsdelivr.net/npm/@adalong/widget@[VERSION]/dist/adalongWidget.js"></script>

Start

First, you need a tag in which to put the widget. For example:

<div id="widget"></div>

You can define two different types of media sources: collections & products.
Add the data-products attribute to load the media linked to the provided products.
Add the data-collections attribute to load the media linked to the provided collections.
Those values must be an array of strings referring to respectively the product references and the collection ids.

<div 
  id="widget" 
  data-products='["PRODUCT_REF1", "PRODUCT_REF1", ...]'
  data-collections='["COLLECTION_ID1", "COLLECTION_ID2", ...]'>
</div>

In case you don't specify any data-* attributes, the media would come from the fallback sources defined in the widget configuration.

Then you can instantiate the widget with your API key and settings and load it by giving the CSS selector of the DOM element.

const adalongWidget = new AdalongWidget('token', { id: 'customUniqId' });

await adalongWidget.load('#widget')

console.log(adalongWidget.layout) // carousel, mosaic or wall

Once instantiated, all widgets in the page can also be retrieved using the global object window.adalongWidgetAPI.

// subscribe on events for all widgets
window.adalongWidgetAPI.widgets.forEach((widget) => widget.onEvent(...))

// find a particular widget from another script in the page
window.adalongWidgetAPI.widgets.find((widget) => widget.id === 'customUniqId')

Settings

Another argument can be passed during instantiation to override the default settings.

await adalongWidget.load('#widget', {
  ...customSettings
});

Those settings are documented as typescript interface in src/types.ts

Events

You can also subscribe to events

adalongWidget.onEvent('postOpened', (event) => {
  console.log(event.post)
  // console.log(event.product)
  // console.log(event.position)
  // console.log(event.direction)
  // console.log(event.elapsedSeconds)
})

Available events are 'widgetLoaded', 'widgetLoadingFailed', 'thumbnailLoaded', 'thumbnailUnavailable', 'thumbnailHover', 'thumbnailClicked', 'originalPostOpened', 'postOpened', 'postClosed', 'postNavigation', 'videoPlayed', 'carouselArrowClicked', 'shopThisLook', 'minContentNotReached', 'minContentReached', 'widgetViewed'

For more details about events, please refer to the EventMap interface in ./src/types.ts

A custom event is also emitted when a new widget instance is created in the page.

document.addEventListener('adalongWidgetCreated', ({ detail }) => {
  console.log(detail.widget.id)
  // Note that at this point the widget instance should not be loaded yet but
  // you can now wait for the widgetLoaded event or check if the loaded property is true
  if (!detail.widget.loaded) {
    detail.widget.onEvent('widgetLoaded', () => {})
  }
})

Styling

Some tags have classes starting with "adl-wdgt-" to help styling and customizing. You can also override this prefix by passing a string in the config object when instantiating the widget.

new AdalongWidget('token', {
  classPrefix: 'myPrefix'
})

Shop this look

The shop this look links clicks will by default open the product url. This behavior can be overridden by providing a function to the shopThisLookHandler field in the config object.

new AdalongWidget('token', {
  shopThisLookHandler: ({media, product}, targetUrl) => {
      const url = new URL(targetUrl)
      url.searchParams.set('utm_source', 'source')
      url.searchParams.set('utm_medium', 'medium')
      window.open(url.href, '_blank')
  }
})

Facebook Pixel Integration

You can leverage AdAlong widget events in your Facebook Pixel.

Add Facebook Pixel base code

First you have to follow those instructions to create a FB pixel. Once created, you need to add the following base code into the <head> tag of the page. Please note that you should reference your pixel id in two places.

<!-- Facebook Pixel Code -->
<script>
  !function(f,b,e,v,n,t,s)
  {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
  n.callMethod.apply(n,arguments):n.queue.push(arguments)};
  if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
  n.queue=[];t=b.createElement(e);t.async=!0;
  t.src=v;s=b.getElementsByTagName(e)[0];
  s.parentNode.insertBefore(t,s)}(window, document,'script',
  'https://connect.facebook.net/en_US/fbevents.js');
  fbq('init', '{your-pixel-id-goes-here}');
  fbq('track', 'PageView');
</script>
<noscript>
  <img height="1" width="1" style="display:none" 
       src="https://www.facebook.com/tr?id={your-pixel-id-goes-here}&ev=PageView&noscript=1"/>
</noscript>
<!-- End Facebook Pixel Code -->

Track Events in your Facebook Pixel

Track standard Facebook events

Now to send information to Facebook from the AdAlong Widget you can map AdAlong events to Facebook standard events:

adalongWidget.onEvent('widgetLoaded', (event) => {
  fbq('track', 'ViewContent', { posts: event.posts })
})

Here is the full documentation on standard Facebook events

Track custom events

Now if you want to track specifically which post has been opened, and not only viewed, Facebook Pixel allows to track custom events following this model:

adalongWidget.onEvent('postOpened', (event) => {
  fbq('trackCustom', 'PostOpened', {
    post: event.post,
    productIds: event.post.products.map(({ id }) => id)
  })
})

Note that in the example we send information about which products the opened post illustrates.

Debugging

Use npm start to build and watch for changes.

Then use npm link to link this repo to another project in which to require the library.

You can also use node debug.js to directly test the library and display it on http://localhost:9800/?apiKey=yourWidgetKey&products=productRef1,productRef2&collections=collectionId1,collectionId2

Usage no npm install needed!