Quick Start

Get a social feed running on your website in under 5 minutes.

1. Create a Feed

Sign up at the dashboard, connect your social account, and create a new feed. You'll receive an API key for each feed.

2. Add the Widget

Paste this code where you want the feed to appear:

<div class="justembed-feed"
     data-api-key="YOUR_API_KEY"
     data-layout="grid"
     data-columns="3">
</div>

<script src="https://cdn.justembed.app/justembed.js" async></script>

That's it! The widget loads asynchronously and renders inside a Shadow DOM for complete CSS isolation.

Installation

Script Tag (Recommended)

Add the script tag before the closing </body> tag. The async attribute ensures it doesn't block page rendering.

<script src="https://cdn.justembed.app/justembed.js" async></script>

NPM Package

npm install @justembed/widget

import { init } from '@justembed/widget';
init();

Configuration

Configure feeds through data-* attributes on the container element. Server-side settings from the dashboard are merged with client-side attributes.

Layouts

Grid

Uniform grid of posts. Best for Instagram-style photo feeds. Set data-columns to control the number of columns.

<div class="justembed-feed" data-api-key="KEY" data-layout="grid" data-columns="4"></div>

Masonry

Pinterest-style layout that preserves original aspect ratios. Great for mixed content with varying heights.

<div class="justembed-feed" data-api-key="KEY" data-layout="masonry" data-columns="3"></div>

Carousel

Horizontal scrolling carousel with navigation arrows. Ideal for featured content or testimonials.

<div class="justembed-feed" data-api-key="KEY" data-layout="carousel"></div>

Data Attributes

All configuration happens through data-* attributes. Here's a complete example with all options:

<div class="justembed-feed"
     data-api-key="01JXYZ..."
     data-layout="masonry"
     data-columns="3"
     data-limit="20"
     data-theme="dark"
     data-lang="es"
     data-gap="12"
     data-show-header="false"
     data-privacy-mode="true">
</div>

JavaScript API

The widget exposes a global window.JustEmbed API for programmatic control:

// Initialize all feed containers on the page
window.JustEmbed.init();

// Destroy all widget instances and clean up
window.JustEmbed.destroy();

// Refresh all feeds (re-fetch data from server)
window.JustEmbed.refresh();

Localization

The widget supports 6 languages. Set the language with the data-lang attribute:

<div class="justembed-feed" data-api-key="KEY" data-lang="fr"></div>

If data-lang is not set, the widget detects the language from the page's lang attribute or the browser's language setting.

Authentication

The API uses Bearer token authentication. Obtain a session token via magic link login:

POST /api/v1/auth/magic-link
Content-Type: application/json

{ "email": "you@example.com" }

Verify the token from the email link:

GET /api/v1/auth/verify?token=TOKEN

Use the returned session token in subsequent requests:

Authorization: Bearer SESSION_TOKEN

Feeds API

Create Feed Example

POST /api/v1/feeds
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "name": "My Instagram Feed",
  "platform": "instagram",
  "sourceUrl": "https://instagram.com/mybusiness",
  "layout": "grid",
  "columns": 3,
  "limit": 12
}

Response:

{
  "data": {
    "id": "01JXYZ...",
    "name": "My Instagram Feed",
    "apiKey": "feed_abc123...",
    "platform": "instagram",
    ...
  }
}

Embed API

The embed endpoint is used by the widget to fetch feed data. No authentication required — uses the feed's API key.

GET /api/v1/embed/:apiKey

Returns cached feed JSON from KV with stale fallback for maximum performance.

Analytics API

WordPress Integration

Add the widget code to any WordPress page or post using the Custom HTML block:

1. Edit your page in the WordPress block editor
2. Add a Custom HTML block
3. Paste the widget code
4. Publish or update the page

Shopify Integration

For Shopify stores, add the widget to a custom Liquid section:

1. Go to Online Store → Themes → Edit code
2. Create a new section or edit an existing one
3. Paste the widget HTML and script
4. Add the section to your desired page template

GDPR & Privacy

JustEmbed offers a privacy-safe mode that ensures GDPR compliance:

<div class="justembed-feed" data-api-key="KEY" data-privacy-mode="true"></div>

In privacy mode:

• All media is proxied through JustEmbed servers (no direct requests to social platforms)
• No cookies or tracking pixels from third parties
• Analytics use anonymous, aggregated data only

Troubleshooting

Feed shows "No posts to display"

This usually means the feed hasn't been synced yet. Feeds sync automatically every 30 minutes. You can trigger a manual sync from the dashboard.

Widget styles conflict with my site

The widget renders inside a Shadow DOM, so styles are fully isolated. If you see conflicts, ensure you're not using JavaScript that modifies Shadow DOM content.

Images don't load

If using data-privacy-mode="true", ensure your server can reach the JustEmbed proxy endpoint. Check browser console for network errors.

Widget doesn't appear on mobile

Ensure the container element has sufficient width. The widget needs at least 280px width to render. Check for CSS that might be hiding the container.