Example embed API and URL
Create a server-side API (embed API), then add it to the host application to generate a secure embed URL at runtime. The one-time-use URL facilitates the embed and contains parameters that define the user's role, what they can view, and how they can interact with the embedded content.
This document provides an example embed API and breaks down the resulting embed URL.
Because you can use a variety of programming languages and development frameworks to create the embed API, and you may have unique integration requirements, this document doesn't provide step-by-step guidance on creating the embed API. Instead, it highlights an example that can provide helpful context that you can leverage as you develop your own approach.
Example embed API
This example demonstrates a JavaScript-based embed API that securely embeds Sigma content using Node.js and Express. For a step-by-step tutorial on creating this specific embed API, see Embedding 03: Secure Access > Parent application setup. The sample embed API code can be downloaded here.
For additional sample code in other languages, see Sigma Embed Signing Packages.
The example features nine numbered sections with function descriptions:
- Values for the embed_path, embed_secret, and client_id parameters in section 3 are generated by Sigma and must be replaced with applicable values when creating an actual embed API.
- Values for the email, external_user_id, external_user_team, and account_type parameters in section 6 are generated dynamically by the host application and are replaced with applicable values in an actual embed API.
- All other values in the example can remain as shown in an actual embed API.
All required parameters must be passed (or hard-coded for testing) for this example code to work.
The following script demonstrates how to programmatically generate a secure embed URL that ensures the correct parameters and encryption for secure embedding in web applications.
// SIGMA SERVER-SIDE EMBED API - SECURE QUICKSTART
// 1: Require necessary Node.js modules
const express = require('express');
const crypto = require('crypto');
// 2: Initialize an Express application
const app = express();
// 3: Manually set your configuration variables here (example values shown)
const EMBED_PATH = 'https://app.sigmacomputing.com/embed/1-1wCxQYjY6ZN7ku3yS4cQhP';
const EMBED_SECRET = '5417c1270f0f74857c276204c50c9f8ea95c22add08f2edad91d94e06312eefa087f57ccde99330da471ace475b56abe02e73c9702cc1dedc0ca9450ce3c9802';
const CLIENT_ID = '8142a98742522b43d36bfd097b11799047ff0292f11226bdf65c311a6b4681a2';
const PORT = 3000; // Feel free to change the port number as needed
// 4: Server Setup
app.get('/', (req, res) => {
res.sendFile(`${__dirname}/index.html`); // Serve the main HTML file for the root path
});
// 5: Define a route handler for generating Sigma embed URLs
app.get('/api/generate-embed-url', (req, res) => {
try {
// Generate a unique nonce using crypto's UUID
const nonce = crypto.randomUUID();
let searchParams = `?:nonce=${nonce}`;
// 6: Construct required search parameters
searchParams += `&:client_id=${CLIENT_ID}`;
searchParams += '&:[email protected]';
searchParams += '&:[email protected]';
searchParams += '&:external_user_team=Sales_Managers';
searchParams += '&:account_type=Creator';
searchParams += '&:mode=userbacked';
searchParams += '&:session_length=600';
searchParams += `&:time=${Math.floor(new Date().getTime() / 1000)}`;
// 7: Construct the URL with search parameters and generate a signature
const URL_WITH_SEARCH_PARAMS = EMBED_PATH + searchParams;
const SIGNATURE = crypto
.createHmac('sha256', Buffer.from(EMBED_SECRET, 'utf8'))
.update(Buffer.from(URL_WITH_SEARCH_PARAMS, 'utf8'))
.digest('hex');
const URL_TO_SEND = `${URL_WITH_SEARCH_PARAMS}&:signature=${SIGNATURE}`;
// 8: Send the final URL to the requester
res.status(200).json({ url: URL_TO_SEND });
} catch (error) {
console.error('Error generating embed URL:', error.message);
res.status(500).send('Internal Server Error');
}
});
// 9: Start the server
app.listen(PORT, () => {
console.log(`Server listening on port ${PORT}`);
});
Example implementation
The following HTML demonstrates a simple implementation of the example embed API. You can evaluate your embed API using Sigma's embed sandbox or any other preferred page rendering method.
<!DOCTYPE html>
<html style="height: 100%; margin: 0; padding: 0;">
<head>
<title>Sigma Embedding - Secure</title>
<style>
body, html {
height: 100%;
margin: 0;
padding: 0;
display: flex; /* Make the body a flex container */
flex-direction: column; /* Stack flex items vertically */
}
h2 {
/* Optional: Add style for the header if needed */
margin: 0; /* Remove default margin */
padding: 10px; /* Add some padding for aesthetics */
text-align: center; /* Center the header text */
background: #f0f0f0; /* Background color for the header */
}
iframe {
flex-grow: 1; /* Allow the iframe to fill the available space */
width: 100%; /* Full width */
border: none; /* Remove the iframe border */
}
</style>
</head>
<body>
<h2>Sigma - Secure Embed Sample</h2>
<iframe id="sigmaDashboard" frameborder="0"></iframe>
<script>
const URL = "http://localhost:3000/api/generate-embed-url";
fetch(URL)
.then(data => data.json())
.then(res => {
document.getElementById("sigmaDashboard").src = res.url;
})
.catch(e => console.log(e));
</script>
</body>
</html>
Example embed URL
The following screenshot demonstrates the structure of a basic embed URL as viewed in a browser's developer tools.
Secure embed URLs are for one-time use only. The embed URL doesn't work if you copy it from a browser inspection (as shown above) and paste it into another browser.
The example embed URL contains the following base URL (embed path) and key-value pairs for the required parameters. For information about required and optional parameters, see Embed URL parameters.
https://app.sigmacomputing.com/embed/1-6ltYPXP83yDSImER8kxk7A?:nonce=0e01e75cbd32-4972-9792-202bab14dc1e&:client_id=b23c7da5d46e1ba15da610a223e9518fe6a057e1855a48a2f6deddedb208b977&:mode=userbacked&:[email protected]&:external_user_id=sales_managers_123&:external_user_team=sales_managers&:account_type=viewer&:session_length=600&:time=1704743833&:signature=2d127b76084f23b4b47d970a00f074e17063ffe0f1bae002fcc9bdf7cbf7b598
Updated 9 months ago