Integrating Maestro with your existing Web Application
Many Maestro customers build their entire brand websites through Maestro, while others prefer to instead integrate Maestro into something existing.
This guide is for web-based desktop and mobile applications. If instead you wish to integrate Maestro with a native iOS applications, we recommend MaestroKit.
Maestro's Web SDK simplifies the process of embedding Maestro within your application. Optionally, it can also be used to:
- Seamlessly providing Maestro access to authenticated user's within your web application
- Responding to events from Maestro within your web application
For the majority of use cases, Maestro provides simpler alternatives to the Web SDK. Before exploring the Web SDK, we recommend evaluating of either of these approaches will work for you:
- using a sub-domain and linking to Maestro from your existing navigation. Through the richness of Maestro's page and themes editor, it's possible to style your Maestro site so that it appears to users as a seamless addition to your existing website.
- using Maestro to power your entire website, not just the video functionality. Through the theme configuration and content blocks, you can design your website whatever pages and layouts you see fit.
Maestro Web SDK is not required if you simply want to link to Maestro from your existing website. But it's recommended if you want to authenticate users in your own system with Maestro, respond to Maestro's events within your system or to have it appear as an embedded sub-component of your system.
Embedding Maestro within your application
Maestro can be easily embedded in any web application. We support different embedding styles.
Full site embedding: For when you want Maestro to take up all of the real estate on the screen.
Partial site embedding: For when you want Maestro to take up part of the page. For example, if you want to include your own navigate bar (rather than Maestro's) and have Maestro take up the rest of the page.
Full site embedding
Let's start with the most basic example by showing a full-site embedding. We will build on this throughout the guide.
Step 1: Create an index.html and update the REPLACE-ME placeholder with the name of your site slug. The site slug is the name of your site that appears after maestro.tv in the browser URL.
<!DOCTYPE html>
<html>
<head>
<style type="text/css">
.iframe {
height: 100vh;
width: 100vw;
}
</style>
<script src="https://unpkg.com/@maestro_io/web-sdk@1.0.2/dist-umd/maestro-iframe-sdk.js"></script>
</head>
<body>
<div class="page-container">
<div id="maestro-platform" class="iframe"></div>
</div>
<script>
const maestro = new MaestroIFrameSDK({
element: document.getElementById("maestro-platform"),
slug: 'REPLACE-ME'
});
maestro.render();
</script>
</body>
</html>
Step 2: Serve the page
To test this out locally, you can navigate to the directory with your index.html and start a web-server. Here are some approaches for doing this in different languages
- Node
- Python
npm install -g http-server
http-server
python -m SimpleHTTPServer 8080
That's it. When you navigate to the locally running page, you should see that it includes your entire Maestro site.
Partial site embedding
Previously, we included Maestro in an iframe that took up the entire page. Alternatively, you can embed Maestro to any dev. For example, you might have a div with an id of main
<div id="main" class="iframe"></div>
The you can get that element and provide it to the MaestroIFrameSDK
<script>
const maestro = new MaestroIFrameSDK({
element: document.getElementById("main"),
slug: 'REPLACE-ME'
});
</script>
React example application
While the previous examples assume a simple application written in HTML, you actual web application may be written in another popular language such as React. A demo application written in React is also provided on Github. You are free to clone this repository and adjust it to suit your needs. It's available on Github at lessthan3/web-sdk-demo.
Authenticating your provider with Maestro
You web application can authenticate with Maestro by calling the login function.
const test = await maestro.login({
name: 'Craig',
service: 'MY-SERVICE', // The service name goes here
thirdPartyAccountId: 'm0un10',
email: 'craig@maestro.io',
jwt: 'eyJ0eX...' // The User's JWT goes here
// Maestro will decode the JWT token to get name, email, and userId (which is a mapping to the thirdPartyAccountId)
});
By default, Maestro will reject your authentication request unless you've registered your provider via our API.
The service must match the name that was used when registering the provider. If you provided the signing certificate, Maestro will use that to ensure the JWT from your system can additionally be allowed to access Maestro.
When performing a login via the Web SDK, it will make calls to the various backend APIs to implement the needed authentication flow.
After login your application, can retrieve the details of the currently logged in user.
const account = await maestro.getUserAccount();
Subscribing to Maestro events
Once you've instanatiated the MaestroIFrameSDK, you can respond to events using the on function.
maestro.on('subscription:required', (event) => {
console.log(event);
});
maestro.on('locale:change', (event) => {
console.log(event);
});
maestro.on('channel:change', async (event) => {
console.log(event);
});
maestro.on('request:logout', (event) => {
console.log(event);
});
maestro.on('request:login', async (event) => {
console.log(event);
});
| Event Name | Trigger |
|---|---|
request:login | When the user requests a login |
request:logout | When the user requests a logout |
subscription:required | On subscription gate required |
maestro:ready | When Maestro is ready |
locale:change | When the user's locale changes |
channel:change | When the user changes channels |
video:content:ready | When the video content is ready |
navigation:initiated | When navigation is initialised |
Refer to the WebSDK Reference for reference.