Content Metadata & Fallback Mechanism

The Sesamy SDK uses a flexible multi-layered approach to extract content metadata from your pages. This ensures resilience even when article elements don't match your configured selectors, or when content is dynamically generated.

How Metadata Resolution Works

The SDK attempts to find content metadata in the following order:

Configured Element Selectors - Searches for elements using your configured selectors
Direct Element Attributes - Reads attributes directly from the element (e.g., item-src, pass, access-level)
Meta Tags - Falls back to <meta> tags in the document <head>

Resolution Flow

When you call content.get() or content.hasAccess():

javascript

// 1. Find element using configured selector or provided selector
const element = document.querySelector('article');

// 2. Try to extract properties using configured selectors
// Example: look for <h1> for title, <img> for image, etc.

// 3. If not found via selectors, check element's attributes directly
// Example: <article item-src="..." pass="premium">

// 4. If still not found, check meta tags
// Example: <meta property="sesamy:url" content="...">

Meta Tag Reference

Meta tags provide a reliable fallback mechanism when content elements don't have the expected structure. They should be placed in the document <head>.

Standard Meta Tags

All Sesamy-specific meta tags use the sesamy: prefix:

Meta Tag	Property	Description	Example
`sesamy:url`	`url`	Canonical URL of the content	`<meta property="sesamy:url" content="https://example.com/article-123">`
`sesamy:publisher-content-id`	`id`	Unique identifier for the content	`<meta property="sesamy:publisher-content-id" content="article-123">`
`sesamy:pass`	`pass`	Required pass(es) for access (comma-separated)	`<meta property="sesamy:pass" content="premium,subscriber">`
`sesamy:paywall-url`	`paywallUrl`	Paywall configuration URL (determines access level automatically)	`<meta property="sesamy:paywall-url" content="https://paywalls.example.com/premium">`
`sesamy:access-level`	`accessLevel`	Access level override: `public` or `logged-in` (typically only for non-paywalled content)	`<meta property="sesamy:access-level" content="public">`
`sesamy:title`	`title`	Article title	`<meta property="sesamy:title" content="Breaking News Article">`
`sesamy:excerpt`	`excerpt`	Article description/excerpt	`<meta property="sesamy:excerpt" content="Short description...">`
`sesamy:image`	`image`	Featured image URL	`<meta property="sesamy:image" content="https://example.com/image.jpg">`
`sesamy:price`	`price`	Price amount	`<meta property="sesamy:price" content="9.99">`
`sesamy:currency`	`currency`	Currency code	`<meta property="sesamy:currency" content="USD">`

Open Graph Fallbacks

The SDK also supports Open Graph meta tags as fallbacks for some properties:

OG Tag	Sesamy Property	Example
`og:url`	`url`	`<meta property="og:url" content="https://example.com/article">`
`og:title`	`title`	`<meta property="og:title" content="Article Title">`
`og:description`	`excerpt`	`<meta property="og:description" content="Description">`
`og:image`	`image`	`<meta property="og:image" content="https://example.com/image.jpg">`

Note: Sesamy-specific meta tags take precedence over Open Graph tags.

Best Practices

1. Always Set a Unique URL

Every published article should have its own unique URL:

html

<!-- Preferred: On the article element -->
<article item-src="https://example.com/articles/breaking-news-2024">...</article>

<!-- Fallback: As a meta tag -->
<meta property="sesamy:url" content="https://example.com/articles/breaking-news-2024" />

2. Use Publisher Content ID

Set a stable identifier that persists even if the URL changes:

html

<!-- Preferred: On the article element -->
<article
  item-src="https://example.com/articles/breaking-news-2024"
  publisher-content-id="article-12345"
>
  ...
</article>

<!-- Fallback: As a meta tag -->
<meta property="sesamy:publisher-content-id" content="article-12345" />

This allows you to:

Change article URLs without losing access history
Track content across different environments (dev/staging/prod)
Maintain consistent analytics

3. Use Paywall to Determine Access Level

The SDK automatically determines the access level from your paywall configuration:

LOGIN template → logged-in access
BOXES template → entitlement access

You typically don't need to set access-level manually. Only set it when:

Content is public (no paywall needed)
Content requires logged-in but has no paywall URL
Working with content containers outside of articles

html

<!-- The paywall determines access level automatically -->
<article
  item-src="https://example.com/articles/premium-content"
  publisher-content-id="article-12345"
  pass="premium,subscriber"
  paywall-url="https://paywalls.example.com/premium"
>
  <h1>Premium Article Title</h1>

  <!-- Child elements can access parent's properties -->
  <sesamy-content-container>
    <!-- This automatically inherits pass, paywall-url, etc. -->
    <p class="premium-content">Locked content here...</p>
  </sesamy-content-container>

  <sesamy-paywall></sesamy-paywall>
</article>

4. Set Properties at the Article Level

Place metadata attributes on the article element so they're accessible to all child elements and content containers.

5. Use Meta Tags for Single-Article Pages

For pages with a single article, meta tags provide a clean global configuration:

html

<head>
  <meta property="sesamy:url" content="https://example.com/articles/breaking-news" />
  <meta property="sesamy:publisher-content-id" content="article-12345" />
  <meta property="sesamy:pass" content="premium" />
  <meta property="sesamy:paywall-url" content="https://paywalls.example.com/premium" />
  <!-- access-level not needed - inferred from paywall template -->

  <!-- Open Graph tags as fallback -->
  <meta property="og:title" content="Breaking News Article" />
  <meta property="og:description" content="Latest updates on..." />
  <meta property="og:image" content="https://example.com/image.jpg" />
</head>

6. Combining Approaches

You can mix approaches for maximum flexibility:

html

<head>
  <!-- Global defaults -->
  <meta property="sesamy:pass" content="premium" />
  <meta property="sesamy:paywall-url" content="https://paywalls.example.com/premium" />
</head>

<body>
  <!-- Article-specific overrides -->
  <article
    item-src="https://example.com/vip-article"
    publisher-content-id="article-99999"
    pass="vip"
  >
    <!-- Overrides the meta tag -->
    ...
  </article>
</body>

Element Attributes Reference

When placing attributes directly on elements, use these attribute names:

Attribute	Description	Example
`item-src`	Content URL	`item-src="https://example.com/article"`
`publisher-content-id`	Unique content ID	`publisher-content-id="article-123"`
`pass`	Required pass(es)	`pass="premium,subscriber"`
`paywall-url`	Paywall URL (determines access level)	`paywall-url="https://paywalls.example.com/test"`
`access-level`	Access level override (typically only for public/logged-in content)	`access-level="public"`
`price`	Price amount	`price="9.99"`
`currency`	Currency code	`currency="USD"`

Access Level Options

Automatic Detection (Recommended)

When you provide a paywall-url, the SDK automatically determines the access level from the paywall template:

LOGIN template → logged-in access (authentication required)
BOXES template → entitlement access (paid subscription/purchase required)

html

<!-- Access level automatically determined from paywall -->
<article item-src="https://example.com/article" paywall-url="https://paywalls.example.com/premium">
  Premium content
</article>

Manual Override

You can explicitly set access-level for content without paywalls:

`public`

Content is freely accessible to everyone. No authentication or entitlement check is performed.

html

<article access-level="public">Free content</article>

`logged-in`

Content requires user authentication but no paid entitlement.

html

<!-- For member-only content without a paywall -->
<article access-level="logged-in">Members-only content</article>

`entitlement`

Content requires a valid entitlement (subscription or purchase). This is the default when a paywall is present.

html

<!-- Typically inferred from paywall, rarely needs to be set manually -->
<article access-level="entitlement" pass="premium">Premium content</article>

When to Use access-level

✅ Use access-level when:

Content is public and you want to skip access checks
Content requires logged-in but has no paywall
Working with <sesamy-content-container> outside of article context

❌ Don't use access-level when:

You have a paywall-url (the paywall determines this automatically)
You're setting up standard paywalled articles

Common Patterns

Pattern 1: News Article with Paywall

html

<!-- Access level automatically determined from paywall template -->
<article
  item-src="https://news.example.com/2024/breaking-story"
  publisher-content-id="news-2024-001"
  pass="subscriber"
  paywall-url="https://paywalls.example.com/subscriber-only"
>
  <h1>Breaking: Major Event Unfolds</h1>
  <p class="excerpt">Public excerpt visible to everyone...</p>

  <sesamy-content-container>
    <div class="premium-content">
      <p>Full story for subscribers only...</p>
    </div>
  </sesamy-content-container>

  <sesamy-paywall></sesamy-paywall>
</article>

Pattern 2: Blog Post with Free Access

html

<article
  item-src="https://blog.example.com/how-to-guide"
  publisher-content-id="blog-123"
  access-level="public"
>
  <h1>How-To Guide</h1>
  <div class="content">
    <p>Free content accessible to everyone...</p>
  </div>
</article>

Pattern 3: Members-Only Content

html

<article
  item-src="https://community.example.com/member-discussion"
  publisher-content-id="discussion-456"
  access-level="logged-in"
>
  <h1>Member Discussion Forum</h1>
  <div class="content">
    <p>Content visible to logged-in members...</p>
  </div>
</article>

Troubleshooting

Content Not Detected

If the SDK can't find your content:

Check element exists: Verify the element is in the DOM
Verify attributes: Ensure attributes are spelled correctly (kebab-case)
Add meta tags: Use meta tags as a reliable fallback
Check console: Look for SDK errors or warnings

Access Check Fails

If hasAccess() returns unexpected results:

Verify URL is set: Content must have a valid url or item-src
Check pass configuration: Ensure the pass matches user's entitlements
Review access level: Confirm the access level matches your intent
Test meta tag fallback: Add meta tags to rule out selector issues

Properties Not Inherited

If child elements can't access parent properties:

Set on parent: Place attributes on the article container, not child elements
Check attribute names: Use exact attribute names (e.g., item-src, not itemSrc)
Verify parent structure: Ensure the parent element matches configured selectors

Content Metadata & Fallback Mechanism ​

How Metadata Resolution Works ​

Resolution Flow ​

Meta Tag Reference ​

Standard Meta Tags ​

Open Graph Fallbacks ​

Best Practices ​

1. Always Set a Unique URL ​

2. Use Publisher Content ID ​

3. Use Paywall to Determine Access Level ​

4. Set Properties at the Article Level ​

5. Use Meta Tags for Single-Article Pages ​

6. Combining Approaches ​

Element Attributes Reference ​

Access Level Options ​

Automatic Detection (Recommended) ​

Manual Override ​

public ​

logged-in ​

entitlement ​

When to Use access-level ​

Common Patterns ​

Pattern 1: News Article with Paywall ​

Pattern 2: Blog Post with Free Access ​

Pattern 3: Members-Only Content ​

Troubleshooting ​

Content Not Detected ​

Access Check Fails ​

Properties Not Inherited ​

See Also ​

Content Metadata & Fallback Mechanism

How Metadata Resolution Works

Resolution Flow

Meta Tag Reference

Standard Meta Tags

Open Graph Fallbacks

Best Practices

1. Always Set a Unique URL

2. Use Publisher Content ID

3. Use Paywall to Determine Access Level

4. Set Properties at the Article Level

5. Use Meta Tags for Single-Article Pages

6. Combining Approaches

Element Attributes Reference

Access Level Options

Automatic Detection (Recommended)

Manual Override

`public`

`logged-in`

`entitlement`

When to Use access-level

Common Patterns

Pattern 1: News Article with Paywall

Pattern 2: Blog Post with Free Access

Pattern 3: Members-Only Content

Troubleshooting

Content Not Detected

Access Check Fails

Properties Not Inherited

See Also