Customize your embedded item

TABLE OF CONTENTS

EX.CO embed events
How to subscribe
List of events
Embed when using Content Security Policy (CSP)
Embed Best Practices

Embed parameters can be added to the <div class="playbuzz"> element to customize it. The supported parameters are listed below.

Parameter	Description	Default
data-id	the id of the item to embed (required)	-
data-show-share	show the share bars	true
data-show-info	show the cover and details of the item	true

EX.CO embed events

Embed events are the way to subscribe to events happening in the EX.CO embedded item., They are dispatched to the parent embedding page, in order for the embedding page to subscribe.

Assuming you have EX.CO story item embedded in your page, you should use the code below in the <body> tag:

 document.body.addEventListener('pbItemEvent', function (e) {
    
    var eventName = e.detail.name;
    var eventData = e.detail.data;
    
    console.log(eventName); // i.e. 'pb.item.scroll-top-into-view'
    console.log(eventData); // i.e. { id: '7cb13e50-8295-4573-ad49-6b5ba7aab278', title: 'my story title', description: 'an example story description' }
 });

List of events

name	data	description
pb.item.load	`{id}`	fired when the item has finished loading
pb.item.scroll-top-into-view	`{id, title, description}`	fired when the item enters the user’s viewport
pb.section.flip	`{}`	fired when the user flips a flip card
pb.section.poll-vote	`{sectionId, sectionIndex, questionId, questionText, answerId, text, itemId}`	fired when the user votes on a poll
pb.section.quiz-question-answered	`{answerId, answerText, questionId, questionIndex, sectionId, sectionIndex}`	fired when the user answers a quiz question
pb.section.quiz-result	`{resultId, resultText, sectionId, sectionIndex}`	fired after the user has completed a quiz and received their result
pb.section.trivia-question-answered	`{answerId, answerText, questionId, questionIndex, sectionId, sectionIndex}`	fired when the user answers a trivia question
pb.section.trivia-result	`{resultId, resultText, sectionId, sectionIndex}`	fired after the user has completed a trivia and received their result
pb.section.rank	`{direction, sectionId, sectionIndex}`	fired when the user votes on a ranked section

Embed when using Content Security Policy (CSP)

The following is a tech guide aimed to help publishers that are using CSP headers and want to embed EX.CO items on their pages.

CSP reference documentation can be found here:

https://content-security-policy.com/

There are many ways to implement CSP on a page, this guide aims to help set the correct CSP attributes depending on Strictness level.

In some cases, some functionality might still be blocked or not work as expected and the attributes will have to be set according to your use case.

Sources we commonly use (this might change /update over time):

Source/Attrubute value	Description
'unsafe-inline'	we load scripts from JS onto the html
*.ex.co	EX.CO domain
*.playbuzz.com	Playbuzz domain (owned by EX.CO)
*.avplayer.com	Channels (mcd) player + analytics
www.google-analytics.com	google analytics
www.google.com	google analytics / recaptcha for Poll & Lead Form
www.googletagmanager.com	Initem ads / Channels ads
www.googleadservices.com	Initem ads / Channels ads
googleads.g.doubleclick.net	Initem ads / Channels ads
www.gstatic.com	recaptcha for Poll & Lead Form

In cases where custom integrations are implemented for an item Pixels/HubSpot etc, these specific sources need to be added to the example below. 3rd party embedded content (ex. YouTube) needs to be added to allowed sources as well.

Simple: default-src defines all sources, without going into specific granulation (script-src, frame-src, etc), Images and Videos will load from any source.

<meta http-equiv="Content-Security-Policy" content="default-src 'unsafe-inline' *.ex.co *.playbuzz.com player.avplayer.com www.google-analytics.com www.google.com www.googletagmanager.com www.googleadservices.com googleads.g.doubleclick.net www.gstatic.com; img-src * data: blob; media-src * data: blob:; worker-src blob:">

Strict media sources: like the example above but with media sources limited to media uploaded to Ex.Co, AJAX requests are limited as well.

<meta http-equiv="Content-Security-Policy" content="default-src 'unsafe-inline'; script-src 'unsafe-inline' *.ex.co *.playbuzz.com *.avplayer.com www.google-analytics.com www.google.com www.googletagmanager.com www.googleadservices.com googleads.g.doubleclick.net www.gstatic.com; frame-src *.ex.co *.playbuzz.com www.google.com doubleclick.net; connect-src *.ex.co *.playbuzz.com; img-src *.ex.co *.playbuzz.com *.avplayer.com www.google-analytics.com www.google.com data:; media-src *.ex.co *.playbuzz.com data: blob:;">

Strict with granular attributes: This will allow most Ex.Co functionality but defines each CSP attribute separately. Any additional sources (For Pixels/Hubspot/3rd Party embeds like Youtube/etc) will need to be added manually under the correct attribute.

<meta http-equiv="Content-Security-Policy" content="default-src 'unsafe-inline'; script-src 'unsafe-inline' *.ex.co *.playbuzz.com *.avplayer.com www.google-analytics.com www.google.com www.googletagmanager.com www.googleadservices.com googleads.g.doubleclick.net www.gstatic.com; frame-src *.ex.co *.playbuzz.com www.google.com doubleclick.net; connect-src *.ex.co *.playbuzz.com; img-src *.ex.co *.playbuzz.com *.avplayer.com www.google-analytics.com www.google.com data:; media-src *.ex.co *.playbuzz.com data: blob:;">

Embed Best Practices

Separate the embed script tag from the div tag, put the script tag in the html head and the div where you would like the item to render.

Bad Example:

<!DOCTYPE html>
<html>
<head>
<title>Page Title</title>
</head>
<body>
<script>(function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(d.getElementById(id))return;js=d.createElement(s);js.id=id;js.src='https://stg-embed.ex.co/sdk.js';fjs.parentNode.insertBefore(js,fjs);}(document,'script','playbuzz-sdk'));</script>
<div class="playbuzz" data-id="5e51b385-64c4-4e0b-90ea-b9793637377c" data-show-share="false" data-show-info="false"></div>
</body>
</html>

Good Example:

<!DOCTYPE html>
<html>
<head>
<title>Page Title</title>
<script>(function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(d.getElementById(id))return;js=d.createElement(s);js.id=id;js.src='https://stg-embed.ex.co/sdk.js';fjs.parentNode.insertBefore(js,fjs);}(document,'script','playbuzz-sdk'));</script>
</head>
<body>
<div class="playbuzz" data-id="5e51b385-64c4-4e0b-90ea-b9793637377c" data-show-share="false" data-show-info="false"></div>
</body>
</html>

If you have more than one items in the same page, do not include the embed script tag twice,