Configure a shareable link for an embed
You can enable your embed users to share workbooks, explorations, or bookmarks with other users using a link with your own domain name. Link sharing is not available for page or single element embeds.
These links can be copied and pasted, allowing recipients to access the content directly in your application. In addition, you can include the shareable link in the embed menu, embed footer, and scheduled export email notifications by configuring the workbook:sharinglink:update
iframe event. See Implement inbound and outbound events in embeds for details.
For a full example implementation, see Embedding 17: Link Sharing QuickStart and the accompanying sample code in the GitHub repo.
Set up a shareable URL for your embed
To enable your embed users to share links, update your application code as follows:
-
Extract the
exploreKey
using theworkbook:exploreKey:onchange
iframe event. See Implement inbound and outbound events in embeds. -
Append a parameter that contains the
exploreKey
to your host application URL whenever an embed user makes or updates an exploration in your application.For example:
window.addEventListener('message', function (event) { if (event.source === document.getElementById('sigma-iframe').contentWindow && event.origin === "https://app.sigmacomputing.com") { // Handle exploreKey changes if (event.data.type === 'workbook:exploreKey:onchange') { // Append exploreKey to your URL params.append(":exploreKey", event.data.exploreKey); } } });
-
Configure your application to parse the
exploreKey
from the URL when an embed user follows a link. This step allows your app to generate a secure embed URL for the embed user with theexploreKey
so that Sigma can render the corresponding embed view. See Example embed API and URL for a detailed example of how to generate a secure embed URL in your application.For example:
// Handle exploreKey if present const exploreKey = req.query.exploreKey; // Append exploreKey, if present, to the secure embed URL that will be passed to the iframe if (exploreKey) { searchParams += `&:explore=${exploreKey}`; } searchParams += `&:bookmark=&{bookmarkId}`;
-
[optional] If you want your embed users to be able to share bookmarks, repeat steps 1 through 3 to extract the
bookmarkId
using theworkbook:bookmark:onchange
iframe event, append it to your host application URL, and include it as a parameter when generating your secure embed URL.For example:
window.addEventListener('message', function (event) { if (event.source === document.getElementById('sigma-iframe').contentWindow && event.origin === "https://app.sigmacomputing.com") { // Handle bookmarkId changes if (event.data.type === 'workbook:bookmark:onchange') { // Append bookmarkId to your URL params.append(":bookmarkId", event.data.exploreKey); } } });
Example appending the bookmarkId to the embed URL:
// Handle bookmark if present const bookmarkId = req.query.bookmarkId; // Append bookmarkId, if present, to the secure embed URL that will be passed to the iframe if (bookmarkId) { searchParams += `&:bookmark=${bookmarkId}`; }
After you complete the above steps, users can share embeds with each other by copying and pasting the application URL from the browser address bar.
Add sharing functionality to your application
-
Using
workbook:sharinglink:update
, provide the URL in thesharingLink
property that will appear in the embed menu, embed footer, and scheduled exports. Include theexploreKey
parameter in this link if you want the embed users to share explorations by default. -
[optional] If you want to give the embed user the option to send a link to the current exploration or a link to the original workbook, supply a second URL that includes the value from the
exploreKey
parameter in thesharingExplorationLink
property. If you want your users to always share their current exploration, you can choose to include theexploreKey
in the value forsharingLink
and omit thesharingExplorationLink
. See Implement inbound and outbound events in embeds for details.For example:
// Function to send sharing links back to Sigma function sendSharingLinks() { const baseUrl = window.location.origin + window.location.pathname; const sharingLink = currentBookmarkId ? `${baseUrl}?&bookmarkId=${currentBookmarkId}` : baseUrl; const sharingExplorationLink = currentExploreKey ? currentBookmarkId ? `${baseUrl}?exploreKey=${currentExploreKey}&bookmarkId=${currentBookmarkId}` : `${baseUrl}?exploreKey=${currentExploreKey}` : null; iframe.contentWindow.postMessage( { type: "workbook:sharinglink:update", sharingLink: sharingLink, sharingExplorationLink: sharingExplorationLink, }, "https://app.sigmacomputing.com" ); }
Sigma loads the URL you supply using this event to anyone given this sharing link. Ensure that your application authenticates users before displaying the content.
Test the sharing links in your embed
After you complete the steps to set up sharable URLs and add them to your application, test the results in your application.
-
Confirm that a share icon appears in the footer of your embedded content and that the Share... option appears in the embed menu.
If you configured your embed to exclude a footer, you can construct your own share modal or button in your application and supply the sharing link to your users that way.
-
Start an exploration on your embedded content, then click Share.
-
In the Share this content modal, confirm that the Link to current exploration checkbox appears.
The Link to current exploration checkbox appears only if the user has an active exploration on the embed and the embed application developer supplied a
sharingExplorationLink
. -
Click Copy Link to test the link with the checkbox unchecked. In a new private browser window, test the link to confirm that your user authentication works as you have configured it for your embed and that the page resolves to the URL configured in the
sharingLink
property. -
If you have a Link to exploration checkbox, check that box, then click Copy Link again. In a new private browser window, test the link to confirm that your user authentication works as you have configured it for your embed and that the page resolves to the URL configured in the
sharingExplorationLink
property. -
In the embed menu, click Schedule exports....
-
Create a new export schedule to send to your own email address, then click More > Send now.
-
Confirm that the email you receive contains an Open button. Click the Open button to confirm that your user authentication works as you have configured it for your embed and that page resolves to the URL configured in the
sharingLink
property.
Updated 2 months ago