Getting Started with FlockSDK

FlockSDK makes it simple to embed referral experiences on your website. This guide walks through the two main flows:
  1. Referrer β€” the customer who sees and interacts with the referral widget.
  2. Invitee β€” the visitor who lands on your site with a referral code.
FlockSDK is available via CDN, so you can add it to any webpage with just a script tag.

🧩 Installation

Add the following to your HTML page:
<!-- SDK JavaScript -->
<script src="https://app.withflock.com/public/sdk-js/index.js"></script>

<!-- SDK Styles -->
<link href="https://app.withflock.com/public/sdk-js/style.css" rel="stylesheet" />
Make sure this is loaded before you interact with FlockSDK in your scripts.

πŸ‘₯ Use Case: Referrer Setup

The referrer is your existing customer. The main flow here is:
  1. Initialize the SDK
  2. Identify the customer
  3. Show the referral placement

Example

<script>
  window.addEventListener('DOMContentLoaded', async () => {
    window.FlockSDK.shared.init({
      apiKey: 'YOUR_PUBLIC_API_KEY',
      environment: 'production', // or 'test'
    });

    await window.FlockSDK.shared.identify({
      externalUserId: 'referrer_123',
      email: 'referrer@example.com',
      name: 'Referrer',
    });

    // Show the referral placement (Placement ID can be found in the Flock campaign dashboard)
    await window.FlockSDK.shared.addPlacement('referrer');
  });
</script>
New: Use addPlacement(placementId) on the singleton for opening campaign pages. Each campaign component now has a unique placementId for robust and future-proof integration.
A placement renders a Flock referral modal within your app, making it easy to prompt users to share and participate in your referral program.

Example

await window.FlockSDK.shared.addPlacement('referrer');
  • The legacy renderWidget() method is now deprecated and will be removed in a future release.
  • Use the Placement API for all new integrations and update any usage of renderWidget() to addPlacement(placementId).

Legacy Widget API (Deprecated)

Deprecated: renderWidget() is now deprecated. Use addPlacement(placementId) for all new integrations.
await window.FlockSDK.shared.renderWidget();

🌱 Use Case: Invitee Setup

The invitee is a visitor referred by someone else. The flow here is:
  1. Capture referral code from the URL
  2. Validate the referral
  3. Create the referral when the invitee signs up

Example

<script>
  window.addEventListener('DOMContentLoaded', async () => {
    window.FlockSDK.shared.init({
      apiKey: 'YOUR_PUBLIC_API_KEY',
      environment: 'production', // or 'test'
    });

    // If the referral code is in the URL like https://example.com/refer/<REFERRAL_CODE>
    const referralCode = window.location.path.split('/').filter(Boolean).pop()?.split('?')[0];

    if (referralCode) {
      const result = await window.FlockSDK.shared.validateReferralCode(referralCode);
      if (result.isValid) {
        console.log('Referral validated:', result.referredBy);
      } else {
        console.warn('Invalid referral code');
      }
    }

    // Later, once the invitee signs up:
    // await window.FlockSDK.shared.identify({...})
    // await window.FlockSDK.shared.createReferral();
  });
</script>

βœ… validateReferralCode(code, options)

This method checks if the referral code is valid and stores the metadata in the specified storage.
// Using default storage (localStorage)
await window.FlockSDK.shared.validateReferralCode('jane123');

// Specifying storage type
await window.FlockSDK.shared.validateReferralCode('jane123', { storage: 'cookie' });
The options parameter supports:
  • storage: Where to store the referral metadata
  • 'localStorage' (default) - Persists in the browser’s local storage, can only be accessed by the same domain.
  • 'cookie' - Useful for cross-subdomain scenarios.
When using cross-subdomain referrals, make sure to use the cookie storage option. This allows the referral data to be shared between subdomains of the same root domain.
// Works across subdomains
// User lands on: shop.example.com
await window.FlockSDK.shared.validateReferralCode('CODE123', { storage: 'cookie' });
// User navigates to: app.example.com
// Referral data is still available!

// Won't work across subdomains
// User lands on: shop.example.com
await window.FlockSDK.shared.validateReferralCode('CODE123', { storage: 'localStorage' });
// User navigates to: app.example.com
// Referral data is lost!
Note: Cookies only work for subdomains of the same root domain. They won’t work across completely different domains (e.g., example.com β†’ another.com).

πŸ†• createReferral()

After the invitee signs up and is identified:
await window.FlockSDK.shared.identify({
  externalUserId: 'invitee_456',
  email: 'invitee@example.com',
  name: 'Invitee',
});

await window.FlockSDK.shared.createReferral(); // Automatically reads referral code from localStorage or cookies
Or you can pass it explicitly:
await window.FlockSDK.shared.createReferral({ referralCode: 'jane123' });

🧠 Tips

  • Always call identify() before addPlacement() or createReferral().

βœ… Recap

RoleKey Methods
Referreridentify, addPlacement
InviteevalidateReferralCode, createReferral
With these tools, you can power robust referral experiences in just a few lines of code. Happy referring! πŸš€