PickFlick Widget SDK

Complete reference for embedding PickFlick widgets on your website.

#Installation

Add the SDK script to your HTML page. This is the only script you need to load.

html

<script src="https://app.pickflick.xyz/developer/sdk/pickflick.js?key=demo"></script>

The SDK automatically registers all custom elements when loaded.

#Quick Start

Here's a minimal example showing an IPTV source widget:

html

<pickflick-source-element orientation="horizontal">
  <pickflick-source-request 
    type="xtreme" 
    host="example.com" 
    username="user123" 
    password="pass123">
  </pickflick-source-request>
  <pickflick-source-all-content></pickflick-source-all-content>
</pickflick-source-element>

#API Key

During beta, use key=demo in the script URL. Production API keys will be available soon.

Note: The demo key is rate-limited. For production use, contact us for a dedicated key.

#pickflick-source-element

The main container for displaying IPTV source information with QR code.

Attributes

Attribute	Type	Default	Description
orientation	"horizontal" \| "vertical"	"vertical"	Layout direction
truncation-preferred	boolean	false	Truncate long URLs

Example

html

<pickflick-source-element orientation="vertical">
  <!-- Child elements go here -->
</pickflick-source-element>

#pickflick-source-request

Configures the source credentials. Must be a child of pickflick-source-element.

Attributes (Xtreme)

Attribute	Type	Default	Description
type	"xtreme"	-	Source type
host	string	-	IPTV server hostname
username	string	-	Account username
password	string	-	Account password

Attributes (URL)

Attribute	Type	Default	Description
type	"url"	-	Source type
url	string	-	M3U/playlist URL

#Content Elements

Control which content is displayed in the source widget.

Shorthand Elements

pickflick-source-all-content - Show all available content
pickflick-source-standard-content - Show default content

Individual Elements

pickflick-source-qr - QR code for scanning
pickflick-source-status - Connection status
pickflick-source-expiry - Expiration date
pickflick-source-actions - Copy/share buttons
pickflick-attribution - PickFlick attribution

#CSS Variables

Customize the appearance using CSS custom properties. All color values support light-dark() for automatic theme switching.

Attribute	Type	Default	Description
--pickflick-color-primary	color	light-dark(#4f46e5, #818cf8)	Primary accent color
--pickflick-color-surface	color	light-dark(#fff, #18181b)	Background color
--pickflick-color-border	color	light-dark(#d4d4d8, #52525b)	Border color
--pickflick-color-on-surface	color	light-dark(#18181b, #f4f4f5)	Text color
--pickflick-qr-size	length	100px	QR code dimensions
--pickflick-padding	length	1.25rem	Internal padding

Example

css

pickflick-source-element {
  --pickflick-color-primary: light-dark(#7c3aed, #a78bfa);
  --pickflick-color-surface: light-dark(#faf5ff, #2e1065);
  --pickflick-qr-size: 120px;
}

#importLibrary()

For programmatic usage, use the importLibrary()method to lazily load specific components.

javascript

// Load the widgets library
const { SourceElement, MediaDetailElement } = await pickflick.importLibrary('widgets');

// Create element programmatically
const source = document.createElement('pickflick-source-element');
source.orientation = 'horizontal';
source.initFromXtreme({
  host: 'example.com',
  username: 'user123',
  password: 'pass123'
});

document.body.appendChild(source);

#pickflick-media-list-element

Display curated lists of movies and TV shows. Perfect for "Popular on Netflix" or custom collections.

Attributes

Attribute	Type	Default	Description
orientation	"horizontal" \| "vertical"	"horizontal"	Scroll direction
compact	boolean	false	Compact card style (200px width)

Example

html

<pickflick-media-list-element orientation="horizontal">
  <pickflick-media-keyword-search-request 
    query="Popular on Netflix"
    network="213">
  </pickflick-media-keyword-search-request>
</pickflick-media-list-element>

#Request Elements

Configure the data source for the media list using one of these request elements.

pickflick-media-keyword-search-request

Fetch media by keyword search, optionally filtered by network.

Attribute	Type	Default	Description
query	string	-	Search query (e.g., 'Popular on Netflix')
network	string	-	TMDB network ID (213=Netflix, 1024=Prime)

pickflick-media-ids-request

Fetch specific media items by their TMDB IDs.

Attribute	Type	Default	Description
ids	string	-	Comma-separated TMDB IDs (e.g., '550,680,120')
type	"movie" \| "tv"	"movie"	Media type

Common Network IDs

213 - Netflix
1024 - Amazon Prime Video
2552 - Apple TV+
453 - Hulu
2739 - Disney+

#pickflick-purchase-element

Embeddable purchase widget that launches a Stripe Checkout session for PickFlick Premium (Lifetime — $49 one-time purchase).

Referral Tracking: When you include your API key in the SDK script URL, all purchases made through your widget are automatically tracked as referrals to you.

Attributes

Attribute	Type	Default	Description
button-text	string	"Buy Lifetime — $49"	Custom button label

Events

Attribute	Type	Default	Description
pickflick-purchase-initiated	CustomEvent	-	Fired when checkout session starts. Detail: { plan, sessionId }
pickflick-purchase-error	CustomEvent	-	Fired on checkout error. Detail: { message }

Basic Usage

html

<!-- Include SDK with your API key -->
<script src="https://app.pickflick.xyz/developer/sdk/pickflick.js?key=YOUR_KEY"></script>

<!-- Place the purchase widget -->
<pickflick-purchase-element></pickflick-purchase-element>

Custom Button Text

html

<pickflick-purchase-element
  button-text="Get Premium Access">
</pickflick-purchase-element>

Listen for Purchase Events

javascript

const widget = document.querySelector('pickflick-purchase-element');

widget.addEventListener('pickflick-purchase-initiated', (e) => {
  console.log('Checkout started:', e.detail.sessionId);
});

widget.addEventListener('pickflick-purchase-error', (e) => {
  console.error('Error:', e.detail.message);
});

#Provider Integration Guide

If you run an IPTV service and want your customers to purchase PickFlick Premium directly from your website, follow this guide.

How It Works

You embed the pickflick-purchase-element on your existing payment or download page.

Your customer clicks “Buy Lifetime” and completes checkout via Stripe.

Customer receives a one-time Apple offer code and opens the PickFlick app to redeem it.

All purchases through your widget are tracked as referrals via your API key.

Complete Integration Example

html

<!DOCTYPE html>
<html>
<head>
  <title>My IPTV Service - Get the App</title>
</head>
<body>
  <h1>Watch with PickFlick</h1>
  <p>Get the best viewing experience with PickFlick Premium.</p>

  <!-- 1. Add SDK script with YOUR API key -->
  <script src="https://app.pickflick.xyz/developer/sdk/pickflick.js?key=YOUR_API_KEY"></script>

  <!-- 2. Source widget: show your IPTV source -->
  <pickflick-source-element>
    <pickflick-source-request
      type="xtreme"
      host="your-server.com"
      username="customer_user"
      password="customer_pass">
    </pickflick-source-request>
    <pickflick-source-all-content></pickflick-source-all-content>
  </pickflick-source-element>

  <!-- 3. Purchase widget: one-click premium purchase -->
  <pickflick-purchase-element
    button-text="Upgrade to Premium — $49">
  </pickflick-purchase-element>
</body>
</html>

Referral Tracking

Your API key in the script URL automatically associates all widget interactions with your account. This includes:

Source widget impressions
Purchase conversions from your embedded widgets
Click-through and usage analytics

Tip: Place the purchase widget right next to your source widget for maximum conversion — customers can see the source and buy premium in one flow.

#Events

Listen to widget lifecycle events:

Attribute	Type	Default	Description
pickflick-load	CustomEvent	-	Fired when widget loads successfully
pickflick-error	CustomEvent<{message: string}>	-	Fired on error
pickflick-status-change	CustomEvent<{status: AccountStatus}>	-	Account status updated
pickflick-purchase-initiated	CustomEvent	-	Purchase checkout started
pickflick-purchase-error	CustomEvent	-	Purchase checkout error

javascript

element.addEventListener('pickflick-load', () => {
  console.log('Widget loaded!');
});

element.addEventListener('pickflick-error', (e) => {
  console.error('Widget error:', e.detail.message);
});