​
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. Render the referral widget

​
Example

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

    await sdk.identify({
      externalUserId: 'user_123',
      email: 'jane@example.com',
      name: 'Jane Doe',
    });

    await sdk.renderWidget();
  });
</script>

​
🔒 identify(...)

This step registers your user with Flock and retrieves their referral code.

sdk.identify({
  externalUserId: 'user_123', // Your internal user ID
  email: 'jane@example.com',
  name: 'Jane Doe',
});

You must call identify() before renderWidget().

​
🪄 renderWidget()

Once the user is identified and a campaign is loaded, the SDK injects the referral widget into the page.

​
🌱 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 () => {
    const sdk = new window.FlockSDK({
      apiKey: 'YOUR_PUBLIC_API_KEY',
      environment: 'production',
    });

    // 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 sdk.validateReferralCode(referralCode);
      if (result.isValid) {
        console.log('Referral validated:', result.referredBy);
      } else {
        console.warn('Invalid referral code');
      }
    }

    // Later, once the invitee signs up:
    // await sdk.identify({...})
    // await sdk.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 sdk.validateReferralCode('jane123');

// Specifying storage type
await sdk.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 sdk.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 sdk.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 sdk.identify({
  externalUserId: 'invitee_456',
  email: 'john@example.com',
  name: 'John Smith',
});

await sdk.createReferral(); // Automatically reads referral code from localStorage or cookies

Or you can pass it explicitly:

await sdk.createReferral({ referralCode: 'jane123' });

​
🧠 Tips

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

​
✅ Recap

RoleKey Methods
Referreridentify(), renderWidget()
InviteevalidateReferralCode(), createReferral()

With these tools, you can power robust referral experiences in just a few lines of code.

Happy referring! 🚀