This article is for anyone who wants to use SourceSync on their website, mobile app, desktop app, video game, metaverse, or consumer electronics device in some custom manner. If you would like to use one of our Turnkey Solutions for Web, Audience sites or OTT, please see those respective articles instead or contact your sales rep for more information. This article is technical. Those articles are not.

How SourceSync Works

At its core, SourceSync use an Internet frame (also called an "iframe") to distribute its technology. This is the most secure method possible and comes with zero risk to your app or website. It's also incredibly simple and can be used anywhere.  SourceSync is used today on millions of consumer electronic devices, mobile apps, and even video games using this method.

The SourceSync Overlay

All the magic happens in the overlay. This is where we display information about your content. Everything else except for the iframe is actually optional.

In general, there are only 2 things that can appear in the overlay, a preview (shown below), and details (details are what show after you tap or otherwise engage a preview). Previews can contain nearly anything from tap to dial, a map, or even full videos (letting you implement Picture In Picture if you wanted).

There are currently over 100 types of content that you can use with SourceSync previews.

A default activation preview in standard format (above)

An HTML5 ad-based activation preview, intended for large screen TVs (below)

Use our player, your own, or something different entirely

A SourceSync frame can be told to run in "normal mode" (which means it includes a player), or in "overlay mode" (which means it includes no player, and is transparent, letting you play the content using your own player). You'll want to set your distributions to "overlay mode" if you are using SourceSync with your own player, in a video game, or in a metaverse.

Listen to and control the overlay

SourceSync frames emit events about what is happening inside of them, and they also listen for commands in case you want to control them. This is used so often and is so powerful, that Source built a tool to help people test SourceSync frames and control them. Check it out here.

Player Layers

There are up to 5 total layers that can be involved in a SourceSync frame, but only 2 are required:

1. The SourceSync overlay (required)
2. The SourceSync player (optional)
3. The Secure iframe (required - prevents stealing your users information from content inside the overlay from any 3rd party)
4. Player.js (optional - use this if you want to control or listen to the frame)
5. Your player (optional - you can use the SourceSync player instead).

How player layers work together (open the image in a new tab to expand)...

Examples

Here is A SourceSync frame on top of a YouTube video, appearing at 720x400 (720px is the minimum recommended landscape width)...

If the frame size is taller than wider, like in a column view or in a phone's portrait mode, it will automatically shift to portrait mode, placing activations below in a more compact layout. Here is the same frame displayed at 320x720 (320px is the minimum recommended portrait width)...

Linking your player

You can use SourceSync with any video player, even one you may have written completely from scratch.

You do this using player.js to listen to frame messages, and send commands to the frame when someone does something in your player. This keeps your player and our frame in sync!

Player.js only adds some syntactic sugar to a browser's built-in window.postMessage command to send messages, and the window.message event to listen to message events. This has been standard in all browsers since 2012, as far back as Internet Explorer 10.

Note: Using player.js is nice, but also optional since it's only syntactic sugar. You can implement SourceSync on your web site even if you have to adhere to the most strict government, healthcare or banking safety standards.

Note: You don't have to test without tooling! Controlling frames using Player.js is used so often and is so powerful, we built a tool to help people test SourceSync frames and control them. Check it out here.

Note: These are web instructions. Looking for iOS or Android instructions? See this help article.

Step 1: Add player.js to your page

<script type="text/javascript" src="https://cdn.embed.ly/player-0.1.0.min.js"></script>

Step 2: Add a SourceSync frame to your page

<iframe id="myFrame" allow="autoplay" src="https://experience.sourcesync.io/test-watch-and-shop" width="720" height="720"></iframe> 

Step 3: Attach Player.js to the iFrame

player = new playerjs.Player(window.frames['myFrame'])

That's it! You're now ready to sync your player!

Syncing your player

Step 1: Listen to stuff you care about

Note: Your callback function will be sent the name of the event that occurred [String], and the event payload, which will be an [Object].

// Note: "player" is a SourceSync frame you got from the linking step above
player.on('ready', manifest => {
  player.on('action', myActionCallback)
  player.on('activation', myActivationCallback)
  player.on('click', myClickCallback)
}

Step 2: Send stuff you care about

// Note: "video" is your player
video.addEventListener('play', () => player.send('play'))
video.addEventListener('pause', () => player.send('pause'))
video.addEventListener('seeked', () => player.send('setCurrentTime', video.currentTime))

That's it! Your player now controls the SourceSync frame!

Don't forget play/pause!

Note: Most people opt to place the iframe on top of their player, leaving some space for their own player controls. If you do this, make sure you add a toggle play/pause to your player whenever the frame returns a "click" event, as most players will play/pause when someone clicks on the video content. If you forget this, your users won't keep this functionality!

Note: When using the Source Live Streaming event dashboard, pause, and rewind player functions are not yet supported. A Source live event overlay on a live stream is always live regardless of what the player controls are doing other than the initial "play". 

Don't forget styling!

Now that your player and SourceSync and synchronized, don't forget to style your solution. People often place our frame with their player in the following ways (in order of popularity):

1. On top of their video player, with a little room for their player's bar. Check out this stack overflow article showing how to overlay something on top of a video.
2. In a column to the left or right of their video player (this puts our frame in "portrait" mode automatically).
3. Above or below their video player (depending on how you set the width/height, it may be in portrait or landscape mode).

Orientation Control 

By default, if the frame is wider than it is tall, it will go into "landscape" mode. If it is taller than it is wide, it will go into "portrait" mode.

Landscape mode - preview

Landscape mode - details

Portrait mode - preview

Portrait mode - details

Some customers have asked for the ability to set the mode to portrait or landscape at-will, regardless of the frame size. Source allows control of this by issuing the ‘orientation’ method.  

Set portrait mode. Once done, it will never switch on it's own

player.send(‘orientation’, ‘portrait’) 

Set landscape mode. Once done, it will never switch on it's own

player.send(‘orientation’, ‘landscape’)

Debugging 

When it comes to debugging your experience, we have two powerful tools:

player.js playground (here)

The player.js playground is great for getting a feel for all the methods and events SourceSync frames listen to and emit, and let you control them via UI.

Debug console (press "~" while focused on a source frame)

Source offers a cool debugging console you can use to do all sorts of things, including sending player.js messages from the Source frame to your page and testing to see if your control messages are getting through.

Note: The Source debug console can be a lifesaver while debugging mobile pages, or when using Source frames in mobile apps or games, when it may be extremely difficult or even impossible to see a browser console.

Note: You can disable the debug console from within the admin tool on the distribution settings page.

Note: Not sure what commands exist? type "help"!

Example; Type "pjs click 1" to tell our frame to send a test "click" message with a payload of "1", then just listen for it. If received, communication is getting through. 

Tip: Keeping the console open will show you the messages it hears. Try firing a test event from your browser console. If it pops up in the Source debug console, communication is working.