Appearance

Static Website Integration ​

Learn how to integrate Sesamy paywalls and authentication into your static HTML website using the Scripts Host and HTML data attributes.

Overview ​

Static websites can easily integrate Sesamy functionality by:

  1. Loading the Sesamy bundle via Scripts Host
  2. Adding HTML elements with Sesamy data attributes
  3. Configuring paywalls, pricing, and access control

This approach requires minimal JavaScript and works with any static HTML site.

Basic Setup ​

1. Load Sesamy Script ​

Add the Sesamy bundle to your HTML page using the Scripts Host:

html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My Premium Content</title>

    <!-- Load Sesamy JS Bundle -->
    <script type="module" src="https://scripts.sesamy.com/s/YOUR_VENDOR_ID/bundle/stable"></script>
  </head>
  <body>
    <!-- Your content here -->
  </body>
</html>

Replace YOUR_VENDOR_ID with your actual vendor ID provided by Sesamy.

2. Add Login Button ​

Add a login button to allow users to authenticate:

html
<header>
  <nav>
    <a href="/">Home</a>
    <a href="/articles">Articles</a>

    <!-- Sesamy Login Button -->
    <sesamy-login></sesamy-login>
  </nav>
</header>

The <sesamy-login> component automatically handles user authentication and displays the user's login state.

Component Configuration ​

How Components Find Properties ​

Sesamy components (<sesamy-paywall>, <sesamy-content-container>, etc.) automatically traverse the DOM tree upwards to find configuration properties. This means you can:

  1. Set properties on a parent element - Typically an <article> tag that wraps both the paywall and content container
  2. Set properties directly on the component - For component-specific configuration
  3. Use meta tags - Components will check page meta tags if properties aren't found in the DOM body

This hierarchy allows for flexible configuration and reduces repetition. For example:

html
<!-- Properties on the article tag are inherited by child components -->
<article
  class="sesamy-article"
  publisher-content-id="article-123"
  item-src="https://example.com/articles/premium-article"
  price="9.99"
  currency="USD"
>
  <!-- This paywall inherits properties from the article tag -->
  <sesamy-paywall settings-url="https://api2.sesamy.com/paywalls/YOUR_VENDOR_ID/YOUR_PAYWALL_ID">
  </sesamy-paywall>

  <!-- This content container also inherits from the article tag -->
  <sesamy-content-container lock-mode="proxy">
    <div slot="preview">
      <p>Preview content...</p>
    </div>
  </sesamy-content-container>
</article>

Protecting Content with Paywalls ​

Basic Article with Paywall ​

Use the <article> tag with Sesamy attributes to create a premium article:

Note: You can add a paywall without locking any content. This is useful for subscription pages or donation pages where you want to display pricing options without restricting content access. Simply include the <sesamy-paywall> component without a <sesamy-content-container>.

html
<article
  class="sesamy-article"
  publisher-content-id="article-123"
  item-src="https://example.com/articles/premium-article"
  price="9.99"
  currency="USD"
  paywall-url="https://api2.sesamy.com/paywalls/YOUR_VENDOR_ID/YOUR_PAYWALL_ID"
>
  <h1>Premium Article Title</h1>

  <div class="article-excerpt">
    <p>This is a preview of the premium content...</p>
  </div>

  <sesamy-paywall
    settings-url="https://api2.sesamy.com/paywalls/YOUR_VENDOR_ID/YOUR_PAYWALL_ID"
    item-src="https://example.com/articles/premium-article"
    price="9.99"
    currency="USD"
  >
  </sesamy-paywall>

  <sesamy-content-container
    item-src="https://example.com/articles/premium-article"
    publisher-content-id="article-123"
    lock-mode="proxy"
  >
    <div slot="preview">
      <p>Full premium content is available to subscribers...</p>
    </div>
  </sesamy-content-container>
</article>

Publisher Content ID ​

The publisher-content-id attribute allows you to maintain your own internal reference IDs:

html
<article
  class="sesamy-article"
  publisher-content-id="my-internal-id-12345"
  item-src="https://example.com/articles/premium-article"
>
  <!-- Content -->
</article>

This ID can be used to:

  • Map Sesamy content to your internal database
  • Track analytics and metrics
  • Reference content in your CMS
  • Handle webhooks and callbacks

Single Purchase Pricing ​

Fixed Price Single Purchase ​

Configure a single purchase option with a fixed price:

html
<article
  class="sesamy-article"
  publisher-content-id="article-456"
  item-src="https://example.com/articles/single-purchase-article"
  price="4.99"
  currency="USD"
>
  <h1>Buy This Article</h1>

  <sesamy-paywall
    settings-url="https://api2.sesamy.com/paywalls/YOUR_VENDOR_ID/YOUR_PAYWALL_ID"
    item-src="https://example.com/articles/single-purchase-article"
    price="4.99"
    currency="USD"
  >
    <div slot="features">
      ✔️ One-time purchase<br />
      ✔️ Lifetime access<br />
      ✔️ No subscription required
    </div>
  </sesamy-paywall>
</article>

Subscription and Single Purchase ​

Offer both subscription and single purchase options:

html
<sesamy-paywall
  settings-url="https://api2.sesamy.com/paywalls/YOUR_VENDOR_ID/YOUR_PAYWALL_ID"
  item-src="https://example.com/articles/flexible-article"
  price="2.99"
  currency="EUR"
>
  <div slot="features">
    <h3>Choose your option:</h3>
    <ul>
      <li>Subscribe monthly for unlimited access</li>
      <li>Or buy this article for €2.99</li>
    </ul>
  </div>
</sesamy-paywall>

Content Lock Modes ​

The lock-mode attribute determines how premium content is protected and delivered.

Proxy Lock Mode ​

The most secure option - content is fetched from Sesamy's proxy after authentication:

html
<sesamy-content-container
  item-src="https://example.com/articles/secure-article"
  publisher-content-id="secure-123"
  lock-mode="proxy"
  locked-content-selector=".premium-content"
>
  <div slot="preview">
    <p>Preview content available to everyone...</p>
  </div>
</sesamy-content-container>

<div class="premium-content">
  <!-- This content will be fetched via proxy after authentication -->
  <p>This is the full premium content.</p>
</div>

Embed Lock Mode ​

Content is embedded in the page but hidden until unlocked:

html
<sesamy-content-container
  item-src="https://example.com/articles/embedded-article"
  publisher-content-id="embed-456"
  lock-mode="embed"
>
  <div slot="preview">
    <p>Read the first few paragraphs for free...</p>
  </div>

  <!-- Hidden content that will be revealed when unlocked -->
  <div slot="locked">
    <p>This content is hidden until the user gains access.</p>
    <p>It's embedded in the page but CSS hides it.</p>
  </div>
</sesamy-content-container>

Encode Lock Mode ​

Content is encoded and decoded client-side after authentication:

html
<sesamy-content-container
  item-src="https://example.com/articles/encoded-article"
  publisher-content-id="encode-789"
  lock-mode="encode"
>
  <div slot="preview">
    <p>Free preview section...</p>
  </div>
</sesamy-content-container>

Event Lock Mode ​

Trigger custom JavaScript when content is unlocked:

html
<sesamy-content-container
  item-src="https://example.com/articles/custom-article"
  publisher-content-id="event-101"
  lock-mode="event"
>
  <div slot="preview">
    <p>Custom unlock handling...</p>
  </div>
</sesamy-content-container>

<script>
  document.addEventListener('sesamyUnlocked', (event) => {
    const { itemSrc, publisherContentId } = event.detail;
    console.log(`Content unlocked: ${publisherContentId}`);

    // Custom logic to display content
    loadPremiumContent(publisherContentId);
  });
</script>

Complete Example ​

Here's a complete static HTML page with Sesamy integration:

html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Premium News Article</title>

    <!-- Load Sesamy JS Bundle -->
    <script type="module" src="https://scripts.sesamy.com/s/YOUR_VENDOR_ID/bundle/stable"></script>

    <style>
      body {
        font-family: Arial, sans-serif;
        max-width: 800px;
        margin: 0 auto;
        padding: 20px;
      }
      header {
        display: flex;
        justify-content: space-between;
        align-items: center;
        padding: 20px 0;
        border-bottom: 1px solid #ddd;
      }
      article {
        margin-top: 40px;
      }
      .article-meta {
        color: #666;
        font-size: 0.9em;
        margin-bottom: 20px;
      }
    </style>
  </head>
  <body>
    <header>
      <h1>News Site</h1>
      <sesamy-login></sesamy-login>
    </header>

    <main>
      <article
        class="sesamy-article"
        publisher-content-id="breaking-news-2024-001"
        item-src="https://example.com/articles/breaking-news"
        price="2.99"
        currency="USD"
      >
        <h1>Breaking: Major Discovery Announced</h1>

        <div class="article-meta">
          <span>By Jane Reporter</span> • <span>November 12, 2024</span>
        </div>

        <img
          src="https://example.com/images/discovery.jpg"
          alt="Discovery"
          style="width: 100%; height: auto"
        />

        <p>
          Scientists announced today a groundbreaking discovery that could change everything we know
          about...
        </p>

        <!-- Paywall -->
        <sesamy-paywall
          settings-url="https://api2.sesamy.com/paywalls/YOUR_VENDOR_ID/YOUR_PAYWALL_ID"
          item-src="https://example.com/articles/breaking-news"
          price="2.99"
          currency="USD"
        >
          <div slot="features">
            ✔️ Read this article for $2.99<br />
            ✔️ Or subscribe for unlimited access<br />
            ✔️ Support quality journalism
          </div>
        </sesamy-paywall>

        <!-- Premium Content -->
        <sesamy-content-container
          item-src="https://example.com/articles/breaking-news"
          publisher-content-id="breaking-news-2024-001"
          lock-mode="proxy"
          locked-content-selector="#premium-content"
        >
          <div slot="preview">
            <p><em>Subscribe or purchase to read the full story...</em></p>
          </div>
        </sesamy-content-container>

        <div id="premium-content">
          <p>
            The full details of this discovery reveal that researchers have been working on this
            project for over five years...
          </p>
          <p>
            According to lead scientist Dr. Smith, "This changes our fundamental understanding
            of..."
          </p>
          <h2>Implications</h2>
          <p>The implications of this discovery are far-reaching...</p>
          <!-- More premium content -->
        </div>
      </article>
    </main>

    <script>
      // Listen for Sesamy ready event
      window.addEventListener('sesamyJsReady', () => {
        console.log('Sesamy is ready!');

        // Optional: Custom analytics or tracking
        const article = window.sesamy.content.get('.sesamy-article');
        if (article) {
          console.log('Article detected:', article.id);
        }
      });
    </script>
  </body>
</html>

Access Levels ​

Control who can see content based on authentication and entitlements:

Public Content ​

Anyone can access:

html
<sesamy-content-container access-level="public">
  <!-- Available to everyone -->
</sesamy-content-container>

Logged-In Users Only ​

Requires authentication but no purchase:

html
<sesamy-content-container
  item-src="https://example.com/members-only"
  publisher-content-id="members-123"
  access-level="logged-in"
>
  <div slot="preview">
    <p>Please log in to view this content.</p>
  </div>
</sesamy-content-container>

Entitlement Required ​

Requires purchase or subscription:

html
<sesamy-content-container
  item-src="https://example.com/premium-article"
  publisher-content-id="premium-456"
  access-level="entitlement"
  lock-mode="proxy"
>
  <div slot="preview">
    <p>Premium subscribers only.</p>
  </div>
</sesamy-content-container>

Pass-Based Access ​

Use passes to grant access to specific content tiers:

html
<article class="sesamy-article" publisher-content-id="exclusive-789" pass="premium;vip">
  <!-- Content accessible with 'premium' OR 'vip' pass -->

  <sesamy-content-container>
    <div slot="preview">
      <p>Requires Premium or VIP membership.</p>
    </div>
  </sesamy-content-container>
</article>

Multiple Articles on One Page ​

You can have multiple protected articles on a single page:

html
<!-- Article 1 -->
<article
  class="sesamy-article"
  publisher-content-id="article-001"
  item-src="https://example.com/article-1"
  price="1.99"
  currency="USD"
>
  <h2>First Article</h2>
  <sesamy-paywall
    settings-url="https://api2.sesamy.com/paywalls/YOUR_VENDOR_ID/PAYWALL_1"
    item-src="https://example.com/article-1"
    price="1.99"
    currency="USD"
  >
  </sesamy-paywall>
</article>

<!-- Article 2 -->
<article
  class="sesamy-article"
  publisher-content-id="article-002"
  item-src="https://example.com/article-2"
  price="2.99"
  currency="USD"
>
  <h2>Second Article</h2>
  <sesamy-paywall
    settings-url="https://api2.sesamy.com/paywalls/YOUR_VENDOR_ID/PAYWALL_2"
    item-src="https://example.com/article-2"
    price="2.99"
    currency="USD"
  >
  </sesamy-paywall>
</article>

Troubleshooting ​

Paywall Not Showing ​

  1. Verify your vendor ID is correct
  2. Check browser console for errors
  3. Ensure settings-url is valid
  4. Confirm your paywall is published and active

Content Not Unlocking ​

  1. Check user authentication status
  2. Verify the user has purchased/subscribed
  3. Ensure item-src matches across components
  4. Check publisher-content-id is unique

Styling Issues ​

Customize the appearance with CSS:

css
sesamy-paywall {
  --sesamy-primary-color: #0066cc;
  --sesamy-font-family: 'Helvetica Neue', sans-serif;
}

sesamy-login {
  --sesamy-button-bg: #0066cc;
  --sesamy-button-text: white;
}

Released under the MIT License.

Copyright © 2025 Sesamy AB