Getting Started with FlockSDK
FlockSDK makes it simple to embed referral experiences on your website. This guide walks through the two main flows:
- Referrer — the customer who sees and interacts with the referral widget.
- 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:
- Initialize the SDK
- Identify the customer
- 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>
Placement API (Recommended)
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)
.
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:
- Capture referral code from the URL
- Validate the referral
- 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
Role | Key Methods |
---|
Referrer | identify , addPlacement |
Invitee | validateReferralCode , createReferral |
With these tools, you can power robust referral experiences in just a few lines of code.
Happy referring! 🚀