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.
π§© Installation
Add the following to your HTML page: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
Placement API (Recommended)
New: UseA placement renders a Flock referral modal within your app, making it easy to prompt users to share and participate in your referral program.addPlacement(placementId)
on the singleton for opening campaign pages. Each campaign component now has a uniqueplacementId
for robust and future-proof integration.
Example
- 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()
toaddPlacement(placementId)
.
Legacy Widget API (Deprecated)
Deprecated:renderWidget()
is now deprecated. UseaddPlacement(placementId)
for all new integrations.
π± 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
β
validateReferralCode(code, options)
This method checks if the referral code is valid and stores the metadata in the specified storage.
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 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).
cookie
storage option. This allows the referral data to be shared between subdomains of the same root domain.π createReferral()
After the invitee signs up and is identified:
π§ Tips
- Always call
identify()
beforeaddPlacement()
orcreateReferral()
.
β Recap
Role | Key Methods |
---|---|
Referrer | identify , addPlacement |
Invitee | validateReferralCode , createReferral |