Embedded Self Service Components

The Younium Embedded Self-Service SDK allows you to integrate self-service components directly into your web applications. This provides a seamless customer experience while keeping your users within your own platform.

What You’ll Find Here

This guide covers:

• Overview – Understanding embedded components
• Quick Start – Getting started with the SDK
• SDK Versioning – Managing SDK versions
• Authentication – Generating API tokens
• Available Components – Invoice List, Account Info, Subscription List
• Configuration Options – Customizing component behavior
• Theming – Styling components to match your application
• Subscription Management – Quantity editing and add-ons
• Error Handling – Managing errors and edge cases
• Best Practices – Security and integration guidance

Overview

What are Embedded Components?

Embedded components are JavaScript widgets that render Younium self-service features inside any web property. They handle:

• Data fetching from the Self-Service API
• UI rendering with customizable theming
• Pagination and search
• Error states and loading indicators
• User interactions

Available Components

Prerequisites

To use embedded components, you need:

1. API credentials from the Self-Service Hub
2. A secure backend to generate JWT tokens
3. A web page to host the components

Quick Start

Step 1: Include the SDK

Add the SDK script to your HTML page:

<script src="<https://cdn.younium.com/selfservice-sdk/latest/younium-embedded-sdk.js>"></script>

Or use a specific version:

<script src="<https://cdn.younium.com/selfservice-sdk/v3.0.0/younium-embedded-sdk.js>"></script>

Step 2: Initialize the SDK

const sdk = YouniumEmbedded.init({
  token: '<jwt-from-your-backend>',
  apiEndpoint: '<https://api.selfservice.younium.com>',
  locale: 'en-GB',
  theme: {
    primaryColor: '#0B5FFF',
    fontFamily: 'Inter, sans-serif',
    buttonStyle: 'pill',
    colorMode: 'light'
  },
  onTokenExpired: async () => {
    const newToken = await fetch('/api/refresh-token').then(r => r.text());
    sdk.setToken(newToken);
  }
});

Step 3: Render a Component

sdk.renderComponent('invoice-list', {
  containerId: 'invoice-container',
  options: {
    pageSize: 20,
    showPaymentStatus: true,
    allowPdfDownload: true
  }
});

Step 4: Add a Container

<div id="invoice-container"></div>

SDK Versioning

The Self-Service SDK supports multiple versions to ensure backward compatibility while providing new features.

Available Versions

Version-Specific URLs

Each SDK version is available at a dedicated URL:

<https://selfservice.younium.com/selfservice-sdk/{version}/younium-embedded-sdk.js>

For minified versions:

<https://selfservice.younium.com/selfservice-sdk/{version}/younium-embedded-sdk.min.js>

Selecting a Version

Using the Latest Version

For new integrations, use the latest version:

<script src="<https://selfservice.younium.com/selfservice-sdk/3.0.0/younium-embedded-sdk.js>"></script>

Pinning to a Specific Version

For production stability, pin to a specific version:

<script src="<https://selfservice.younium.com/selfservice-sdk/3.0.0/younium-embedded-sdk.js>"></script>

Cache Busting

Add a query parameter to force cache refresh when updating versions:

<script src="<https://selfservice.younium.com/selfservice-sdk/3.0.0/younium-embedded-sdk.js?v=2025-12-19>"></script>

Version API

The SDK exposes version information programmatically:

// Get version info via API
fetch('<https://selfservice.younium.com/api/sdk/versions>')
  .then(r => r.json())
  .then(versions => console.log(versions));

// Get components for a specific version
fetch('<https://selfservice.younium.com/api/sdk/versions/3.0.0/components>')
  .then(r => r.json())
  .then(components => console.log(components));

Version 3.0.0 Features

The latest SDK version includes:

• Subscription List Component - Full subscription management capabilities
• Quantity Editing - Real-time price calculation for quantity changes
• Add-on Support - Adding products to existing subscriptions
• Tiered Pricing Display - Modal for viewing tiered pricing
• TypeScript Source - Type definitions for better IDE support
• ES Module Support - Compatible with modern bundlers

Testing Versions

Use the Component Test Bed in the Self-Service Hub to test different SDK versions with live data before deploying.

Authentication

Components require a JWT token to access the Self-Service API.

Token Generation Flow

1. Your backend receives a request from the frontend
2. Backend calls Self-Service API with API credentials
3. API returns a JWT token for the specific customer
4. Frontend uses the token to initialize the SDK

Backend Token Request

POST /api/auth/token
Content-Type: application/json
X-API-Key: your-api-key
X-API-Secret: your-api-secret

{
  "customerId": "customer-guid",
  "scopes": ["read:invoices", "read:account"]
}

Required Scopes by Component

Token Expiration

Tokens expire after 1 hour by default. Handle expiration with the onTokenExpired callback:

const sdk = YouniumEmbedded.init({
  token: initialToken,
  onTokenExpired: async () => {
    // Fetch a new token from your backend
    const newToken = await fetch('/api/refresh-token').then(r => r.text());
    sdk.setToken(newToken);
  }
});

Configuration Options

Initialization Options

Instance Methods

Invoice List Component

Display customer invoices with search, pagination, and PDF download.

Basic Usage

sdk.renderComponent('invoice-list', {
  containerId: 'invoices',
  options: {
    pageSize: 10,
    showPaymentStatus: true,
    allowPdfDownload: true
  }
});

Options

Programmatic Control

// Trigger search
YouniumEmbedded.searchInvoices('invoices-component-id');

// Clear search
YouniumEmbedded.clearSearch('invoices-component-id');

// Navigate pages
YouniumEmbedded.changePage('invoices-component-id', 2);

// Download specific invoice
YouniumEmbedded.downloadInvoice('invoice-id');

Account Info Component

Display account information with optional inline editing.

Basic Usage

sdk.renderComponent('account-info', {
  containerId: 'account',
  options: {
    allowEdit: true,
    showDetails: true
  }
});

Options

Editable Fields

When allowEdit: true:

• Invoice email address
• Invoice address

Programmatic Control

// Start editing
YouniumEmbedded.startEditEmail('account-component-id');
YouniumEmbedded.startEditAddress('account-component-id');

// Save changes
YouniumEmbedded.saveEmail('account-component-id');
YouniumEmbedded.saveAddress('account-component-id');

// Cancel editing
YouniumEmbedded.cancelEditEmail('account-component-id');
YouniumEmbedded.cancelEditAddress('account-component-id');

Subscription List Component

Display subscriptions with detailed product information, quantity editing, and add-on support. 

1. Navigate to the Self Service Hub.
2. Under Configuration, select Subscriptions.

Note: The Subscription List component requires SDK version 3.0.0 or later.

Basic Usage

sdk.renderComponent('subscription-list', {
  containerId: 'subscriptions',
  options: {
    allowQuantityEdit: true,
    allowAddons: true,
    showPriceDetails: true,
    expandByDefault: false
  }
});

Options

Subscription Card Features

Each subscription displays:

• Subscription number and status
• Date range (start to end or ongoing)
• Product list with expand/collapse
• Add button for add-on products

Product Line Details

Clicking a product line reveals:

• Charge type (Recurring, One-time, Usage)
• Quantity (for quantity-based charges)
• Unit price and total amount
• Billing period
• Edit button (for editable lines)

Quantity Editing

For quantity-based subscriptions, users can request quantity changes.

Workflow

1. User clicks Edit on a quantity-based product line
2. Modal opens showing current quantity and pricing
3. User enters new quantity
4. Price change is calculated and displayed in real-time
5. User clicks Request Change to submit
6. Confirmation message appears

Price Preview

The modal shows:

• Current quantity and price
• New quantity and estimated price
• Price difference (increase or decrease)

Adding Add-on Products

If add-on products are configured, users can add them to subscriptions.

Workflow

1. User clicks Add button on subscription card
2. Modal opens with available add-on products
3. User selects product and configures quantity
4. User clicks Add to Subscription
5. Request is submitted for processing

Tiered Pricing Display

For products with tiered or volume pricing, a View Pricing link reveals the pricing breakdown.

Programmatic Control

// Toggle subscription expansion
YouniumEmbedded.toggleSubscription('component-id', 'subscription-id');

// Toggle product line expansion
YouniumEmbedded.toggleLine('component-id', 'line-id');

// Open quantity edit modal
YouniumEmbedded.showEditQuantityModal('component-id', 'subscription-id', 'line-id');

// Open add-on modal
YouniumEmbedded.showAddAddonModal('component-id', 'subscription-id');

// Show tiered pricing
YouniumEmbedded.showTieredPricing('component-id', 'line-id');

// Close any modal
YouniumEmbedded.closeModal('modal-id');

Theming

Customize component appearance to match your application.

Theme Options

const sdk = YouniumEmbedded.init({
  token: token,
  theme: {
    primaryColor: '#0B5FFF',     // Main accent color
    fontFamily: 'Inter, sans-serif',
    buttonStyle: 'pill',         // 'rounded', 'pill', 'square'
    colorMode: 'light'           // 'light' or 'dark'
  }
});

Theme Properties

CSS Class Prefix

All component markup uses class names prefixed with:

• SDK v3.x: yem-

Custom CSS

Override styles in your stylesheet:

/* v3.x class names */
.yem-invoice-list {
  border: 1px solid #e5e7eb;
  border-radius: 8px;
}

.yem-button-primary {
  font-weight: 600;
}

Dark Mode

Set colorMode: 'dark' for dark-themed applications:

theme: {
  colorMode: 'dark',
  primaryColor: '#60A5FA'  // Use lighter colors for dark mode
}

Error Handling

Automatic Retries

Network failures trigger automatic retries:

• Configurable retry count (default: 3)
• Exponential backoff between retries
• Final failure surfaces error in component

Error Display

When errors occur, components display user-friendly messages:

Empty States

When no data is available, components show appropriate empty states:

Token Expiration

Handle expired tokens with the callback:

onTokenExpired: async () => {
  try {
    const newToken = await refreshToken();
    sdk.setToken(newToken);
  } catch (error) {
    // Handle refresh failure
    showLoginPrompt();
  }
}

Debug Mode

Enable debug mode for troubleshooting:

const sdk = YouniumEmbedded.init({
  token: token,
  debug: true  // Logs API calls, retries, render steps
});

Best Practices

Security

1. Generate tokens server-side - Never expose API credentials in client code
2. Scope tokens narrowly - Only request scopes you need
3. Handle token expiration - Implement the onTokenExpired callback
4. Use HTTPS - Ensure your site uses SSL/TLS

Performance

1. Lazy load the SDK - Only load when components are needed
2. Destroy unused components - Call destroyComponent() when removing from DOM
3. Use pagination - Set appropriate pageSize values

Integration

1. Version pinning - Pin SDK version in production
2. Test before deploy - Use the Component Test Bed
3. Monitor Activity Log - Track component usage in the Hub

SPA Integration

For Single Page Applications:

// When mounting component
const sdk = YouniumEmbedded.init({ ... });
sdk.renderComponent('invoice-list', { containerId: 'invoices' });

// When unmounting
sdk.destroyComponent('invoices');

// Or destroy everything on route change
sdk.destroy();

Complete Integration Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Customer Portal</title>
  <style>
    .portal-section {
      max-width: 1200px;
      margin: 0 auto;
      padding: 20px;
    }
    .section-title {
      font-size: 24px;
      margin-bottom: 20px;
    }
  </style>
</head>
<body>
  <div class="portal-section">
    <h1 class="section-title">Your Invoices</h1>
    <div id="invoice-container"></div>
  </div>

  <div class="portal-section">
    <h1 class="section-title">Account Information</h1>
    <div id="account-container"></div>
  </div>

  <div class="portal-section">
    <h1 class="section-title">Your Subscriptions</h1>
    <div id="subscription-container"></div>
  </div>

  <script src="<https://selfservice.younium.com/selfservice-sdk/3.0.0/younium-embedded-sdk.js>"></script>
  <script>
    // Get token from your backend
    async function initializePortal() {
      const token = await fetch('/api/get-customer-token')
        .then(r => r.json())
        .then(data => data.token);

      const sdk = YouniumEmbedded.init({
        token: token,
        apiEndpoint: '<https://api.selfservice.younium.com>',
        locale: 'en-US',
        theme: {
          primaryColor: '#2563eb',
          fontFamily: 'system-ui, sans-serif',
          buttonStyle: 'rounded',
          colorMode: 'light'
        },
        onTokenExpired: async () => {
          const newToken = await fetch('/api/refresh-token')
            .then(r => r.json())
            .then(data => data.token);
          sdk.setToken(newToken);
        }
      });

      // Render Invoice List
      sdk.renderComponent('invoice-list', {
        containerId: 'invoice-container',
        options: {
          pageSize: 10,
          showPaymentStatus: true,
          allowPdfDownload: true,
          dateFormat: 'MM/DD/YYYY'
        }
      });

      // Render Account Info
      sdk.renderComponent('account-info', {
        containerId: 'account-container',
        options: {
          allowEdit: true,
          showDetails: true
        }
      });

      // Render Subscription List (requires SDK 3.0.0+)
      sdk.renderComponent('subscription-list', {
        containerId: 'subscription-container',
        options: {
          allowQuantityEdit: true,
          allowAddons: true,
          showPriceDetails: true,
          statusFilter: 'Active'
        }
      });
    }

    initializePortal();
  </script>
</body>
</html>

Troubleshooting

Component Not Rendering

• Verify the container element exists before calling renderComponent
• Check browser console for JavaScript errors
• Enable debug: true to see detailed logs

“Unknown component type” Error

• Check for typos in component type name
• Verify your SDK version supports the component
• The subscription-list component requires SDK 3.0.0+

PDF Downloads Failing

• Verify the token has read:invoices scope
• Check CORS settings in API Credentials
• Ensure your domain is in the allowed origins list

Styling Issues

• Check if host page CSS is overriding component styles
• Verify CSP allows inline styles (or configure a nonce)
• Inspect generated DOM to find correct class names

Token Errors

• Verify token has not expired
• Check that required scopes are included
• Ensure API credentials are active in the Hub