alphaseek
v0.1.0-beta.2
Published
JavaScript/TypeScript library for building referral program with Alphaseek SDK
Downloads
3
Maintainers
Readme
alphaseek.js
JavaScript/TypeScript library for building referral programs with Alphaseek SDK.
Sign up
In order to use the library, please make sure you have signed up with Alphaseek.
Install
npm install alphaseek
Getting started
In your project, authenticate (login) in the appropriate place to get an Auth
instance, which will be used to authenticate a Product
.
import {Auth} from 'alphaseek';
async function init() {
const auth = new Auth();
await auth.login('[email protected]', 'secretpass1234');
// Now we can use auth instead of raw token, which
// atomically keeps track of the signed-in state.
let product = new Product('alphaseek.io', {auth});
// Save product
product = await prod.create();
// Note that from field is the referral code of another referring user.
const user = await new User('[email protected]', {product, from: '916hqpB7'}).create();
// Get user's unique referral link and code
const {url, moniker, score, referrer} = user.referral;
console.log(url); // https://alphaseek.me/i/99PpQrh7
console.log(moniker); // 99PpQrh7
console.log(score); // 1
console.log(referrer.referral.moniker); // 916hqpB7
}
Authentication
To log into your account, use an Auth
as a static class or instantiate a singleton object. It is a single source of truth for your account identity as Alphaseek customer.
Static
import {Auth} from 'alphaseek';
const token = await Auth.login('[email protected]', 'secretPassword');
The token will be stored in the browser's localStorage
if it's available and also in-memory as a static variable.
You can opt-out of storing the token in the browser's localStorage by setting Auth.useLocalStorage = false
before calling login()
.
To log out (invalidate the access token):
const ok = await Auth.logout();
This also clears old token from the localStorage if Auth.useLocalStorage
is set to true
.
Singleton
You can also create an Auth
singleton instance so you could pass it around in other calls.
const auth = new Auth();
const tok = await auth.login('[email protected]', 'secretPassword');
// Create a new product.
const prod = new Product('awesome.app', {auth});
Optionally, you could pass the access token as token
field in the object parameter
like so:
const prod = new Product('awesome.app', {token: tok});
You can also inquire for your account information with
const myInfo = await auth.me();
Product
A Product
is the namespace of a campaign and its User
s.
An account has a default Product
tied to its registered email address's domain name,
for instance, a Product
with alias awesome-app-732109 is tied to a domain name
awesome.app.
An account can create more than one Product
. Product
s cannot share their User
s
across them.
const prod = new Product('awesome.app', {auth});
User
The core of a referral is in the users' interactions. Here are some key points
about a User
:
- only have one referrer (another
User
who refers), but many referrees (otherUser
s whom thisUser
refers to yourProduct
) - owns a unique referral URL and a related referral code (called moniker) per
Product
- owns a referral score that increments when a new
User
is created with his moniker OR when he is created as aUser
with a referral code of someone else (2-side rewarding)
Your user's referral URL has a destination URL that it redirects to. For instance,
you could set it to your signup form page i.e. https://awesome.app/signup
. When it
actually redirects to the destination URL, it adds the following query parameters
?from=916hqpB7&source=alphaseek&type=referral
Your signup form should design a hidden form field that grabs the referral code
from the from
field or use JavaScript to do so to create the User
const urlParams = new URLSearchParams(window.location.search);
if (urlParams.get('source') === 'alphaseek') {
const from = urlParams.get('from');
let user = new User('[email protected]', {from, product});
user = await user.create();
}
Use cases
- 2-sided reward when a user signed up
- Successful purchase with "coupon" code
- Priority queue based on referrals
Referral and Destination URLs
You can set the destination URL where the referral URL will redirect to
by calling update
method on the User
.
You can't change the user's default referral URL.
user = await user.update({redirectUrl: 'https://awesome.app/signup'});
Most of the time, you may want to set a default destination on the Product
either when
creating it or updating it instead of setting one for each User
.
// Create
const prod = new Product('awesome.app', {auth, redirectUrl: 'https://awesome.app/signup'});
// Update
prod = await prod.update({redirectUrl: 'https://signup.awesome.io/form'});