GetSetUp HTML Embed Integration Guide

The GetSetUp (GSU) HTML Embed feature enables partners to integrate GSU content seamlessly into their existing websites. With this setup, partners can offer diverse GSU content (classes, series, articles, etc.) directly on their sites without redirecting users to external pages. This document provides an overview of the integration process, key functions, and example code for various setups.

Overview of GetSetUp HTML Embed

• Purpose: Embed GSU pages within partner websites, keeping users engaged without leaving the site.
• Content Offerings: Include a Discover page (content grid view), Class Watch page, Series page, and Articles page, each featuring specific types of content from GSU.
• Setup Options:
  • Single Page Embed – For partners with static sites (WordPress, CMS), a single iframe can be embedded.
  • Multi-page Embed – For partners with dynamic sites (React, Next.js, Vue.js), the embed package allows integration on different URLs, enabling route-based navigation.

Installation

Install the GSU HTML Embed package using npm:

npm install @getsetup-io/html-embed

Core Integration Methods

1. GSUEmbed.init (Required)

This function initializes the embedded GSU app within a target HTML element on the partner’s site. It requires a targetElementId (ID of the HTML container) and a partnerId (provided by GSU support).

Example:

GSUEmbed.init({
  targetElementId: "iframe-container",
  partnerId: "-gsu-partner-id-"
});

Parameters:

• targetElementId (string, required) – The ID of the HTML element where GSU will be embedded.
• partnerId (string, required) – The unique partner ID assigned by GSU support.

2. Custom Base Path Configuration (Optional)

To host the Discover page at a custom base path (e.g., https://www.example.com/learning/), specify the base URL in the target element using the data-gsuembed-discover-link-template attribute.

Example:

<div id="iframe-container" data-gsuembed-discover-link-template="/learning"></div>

3. Hotlinking other page types (Optional)

Enable hotlinking for the Watch page with custom URL formats by specifying the data-gsuembed-watch-link-template attribute. This allows URLs to follow a specific structure, such as https://www.example.com/classes/yoga-for-beginners/class:abcxyz. It works similarly for the other page templates: data-gsuembed-article-link-template and data-gsuembed-series-link-template.

Example with only watch template:

<div id="iframe-container" data-gsuembed-discover-link-template="/learning" 
  data-gsuembed-watch-link-template="/classes/[classSlug]/[classID]"></div>

Example with all templates:

<div id="iframe-container" data-gsuembed-discover-link-template="/learning" 
  data-gsuembed-watch-link-template="/classes/[classSlug]/[classID]"
  data-gsuembed-article-link-template="/article/[articleID]"
  data-gsuembed-series-link-template="/series/[seriesID]"></div>

4. Authentication & User Session Tracking (Optional)

Our solution provides a seamless way for partners to embed GetSetUp within their platforms, keeping it behind their own authentication systems. This allows partner platforms to control access for authenticated users while leveraging our solution’s features. Below is a guide to implementing and tracking authenticated user sessions with GetSetUp embedded in your platform.

Integration Steps:

1. Embedding GetSetUp Partners can embed the GetSetUp interface directly into their applications. This interface will work behind the partner's authentication, allowing secure access only for authenticated users.

2. Tracking User Sessions (Optional) To track GetSetUp usage by authenticated users, we provide two functions to be used as hooks. These functions capture user sessions by sending data to GetSetUp based on the user's authentication state. This data enables partners to analyze usage patterns and better understand how their users engage with GetSetUp.

Partners can track and manage user sessions using two functions: onAuthSuccess and onAuthReset. These functions capture session data whenever users log in or out.

onAuthSuccess

Called when an authenticated session is detected, this function requires a userId and supports additional optional information.

GSUEmbed.onAuthSuccess({
  userId: "uniqueUserId123",
  additionalInfo: {
    billing_id: "12345",
    plan: "premium"
  }
});

• userId (required) – A unique identifier for the authenticated user.
• additionalInfo (optional) – Object for additional data (e.g., billing ID, subscription plan).

onAuthReset

Called when a user logs out, this function clears session data. No parameters are required.

GSUEmbed.onAuthReset();

Integration Flow Diagram

The following diagram provides an overview of the integration flow:

---
config:
  layout: fixed
---
flowchart TD
    A["Embed GSU on Partner Platform"] --> B["Partner Authenticates User"]
    B --> C{"User Authentication Status"}
    C -- Authenticated --> D["GSUEmbed.onAuthSuccess Called"]
    D --> E["Session Data Sent to GSU"]
    C -- Logged Out --> F["GSUEmbed.onAuthReset Called"]
    F --> G["Session Data Cleared"]

Quick Start Examples

Basic HTML Embed

Note: This example uses just the root path for the discover page "/", (earlier examples used "/learning"). Also the watch page is located at "/classes..." in this example, (earlier examples had used "/watch..."). These are settings and can be set to anything as long as it is consistent throughout an implementation.

<!-- Embed Container Element -->
<div
    id="iframe-container"
    data-gsuembed-discover-link-template="/"
    data-gsuembed-article-link-template="/article/[articleID]"
    data-gsuembed-series-link-template="/series/[seriesID]"
    data-gsuembed-watch-link-template="/classes/[classSlug]/[classID]"
></div>

<!-- Embed Script -->
<script src="https://unpkg.com/@getsetup-io/html-embed/dist/umd/gsu-embed.min.js"></script>
<script>
    GSUEmbed.init({
      targetElementId: "iframe-container",
      partnerId: "-gsu-partner-id-",
      analyticsInfo: "optional-tracking-id"
    });
</script>

Node.js + TypeScript Example

import { init, GSUEmbedOptions } from '@getsetup-io/html-embed';

init({
  targetElementId: "iframe-container",
  partnerId: "-gsu-partner-id-"
});

React + Next.js Example

Discover Page

Note: This example uses "/discover" for the discover page, (earlier examples used "/learning" and just "/").

// Discover Page: /src/app/discover/page.tsx
'use client'
import { init } from "@getsetup-io/html-embed";
import { useEffect } from "react";

export default function DiscoverPage() {
  useEffect(() => {
    init({
      targetElementId: "iframe-container",
      partnerId: "-gsu-partner-id-",
    });
  });

  return (
    <main>
      <div
        id="iframe-container"
        data-gsuembed-discover-link-template="/discover"
        data-gsuembed-article-link-template="/article/[articleID]"
        data-gsuembed-series-link-template="/series/[seriesID]"
        data-gsuembed-watch-link-template="/watch/[classID]"
      ></div>
    </main>
  );
}

Watch Page

// Watch Page: /src/app/watch/[classID]/page.tsx
'use client'
import { init } from "@getsetup-io/html-embed";
import { useEffect } from "react";

export default function WatchPage() {
  useEffect(() => {
    init({
      targetElementId: "iframe-container",
      partnerId: "-gsu-partner-id-",
    });
  });

  return (
    <main>
      <div
        id="iframe-container"
        data-gsuembed-discover-link-template="/discover"
        data-gsuembed-article-link-template="/article/[articleID]"
        data-gsuembed-series-link-template="/series/[seriesID]"
        data-gsuembed-watch-link-template="/watch/[classID]"
      ></div>
    </main>
  );
}

Summary

This integration guide covers embedding, configuration, and user session management for GetSetUp content within partner platforms. By using GSUEmbed.init, along with optional hooks for user session tracking (onAuthSuccess and onAuthReset), partners can provide a seamless experience while keeping GetSetUp content directly on their site. This setup offers a flexible, controlled, and secure way to deliver diverse GSU features to authenticated users.

Example Discover Page:

Example Watch Page: