RefferalLib

Use this Lib for referral tracking.

Demo bot: https://telegram.me/DemoReferalTrackingBot

RefferalLib is core Lib now - installation is not needed!

Getting started

Basic function is track. Prefer to call it on /start:

RefLib.track(trackOptions);

params trackOptions - it is object with callback functions for:

Attribute	Description
onTouchOwnLink()	user touch own ref link
onAlreadyAttracted()	user already attracted
onAttracted(byUser)	user was attracted by other user byUser - it is common user data (fields: nickname, first_name and etc)
linkPrefix	Prefix for link. By default it is "user": https://t.me/botName?start=userID You can change linkPrefix in any time but all old links will be broken! Please check all your deep link params!

See @DemoReferalTrackingBot for details (Available in the Store)

Example

Command /start

// Command /start

// this function will be executed if user poress own ref link
function onTouchOwnLink(){
   Bot.sendMessage("It is your ref link!")
}

// user can restart bot by ref link again
function onAlreadyAttracted(){
   Bot.sendMessage("You already joined")
}

// it is new user. He start bot via ref link
function onAttracted(byUser){
   Bot.sendMessage("Thank you for joining!" +
                    "Your friend TG id is: " + byUser.telegramid)
   // you can add bonus here...
}

RefLib.track({
   onTouchOwnLink: onTouchOwnLink,
   
   onAlreadyAttracted: onAlreadyAttracted,
   
   onAttracted: onAttracted,
   
   // you can use "", "r" and etc for prefix
   // if you change it - you need to pass same linkPrefix for
   //  RefLib.getLink() also!
   // Prefix "user" is used by default
   // linkPrefix: "user",
   
   // you can pass debug for external debug info
   //debug: true,
   
   // we can use List or TopBoardLib for Top List
   // by default TopBoardLib is used
   // useList: false
   
   // if useList - false (TopBoardLib is used)
   // you can pass max board count
   // it is 10 by default
   // topBoardMaxCount: 15
});

Functions

Get Referral link for current user

RefLib.getLink();

will generate link kind http://t.me/botname?start=userUSER_ID

Also you can pass other bot name. For example - it is link for current bot:

RefLib.getLink(bot.name);

will generate link kind http://t.me/botname?start=userUSER_ID

It is possible to change link prefix:

RefLib.getLink(bot.name, "r");

will generate link kind http://t.me/botname?start=rUSER_ID

Get attractor for current user

RefLib.getAttractedBy()

return attractor user data

Remove ref data for

It is test method. You can run it and check ref link again like new user.

RefLib.clearRef()

Get refList

RefLib.getRefList();

return list with attracted users.

Or get for Ref List for another user:

RefLib.getRefList(another_user_id);

This method return users list. You can paginate it, sort, recount it and etc.

then code for /reflist can be:

let refList = RefLib.getRefList();

if (!refList.exist) {
  Bot.sendMessage("No any affiliated users")
  return
}

let users_rows = ""

// only 100 first users here
// for other users you need use pagination:
// https://help.bots.business/bjs/lists#paginating
let users = refList.getUsers();

for (var ind in users) {
  users_rows = users_rows + "\n👤 " + CommonLib.getLinkFor( users[ind] )
}

let msg =
  "*Total users:* " +
  RefLib.getRefCount() +
  "\n _the first user was tracked:_ \n" +
  "   _" +
  refList.created_at +
  "_" +
  "\n----" +
  users_rows
  
Bot.sendMessage(msg);

Get refferals count

RefLib.getRefCount()

or for another user:

RefLib.getRefCount(another_user_id)

Get Top Refferal List

RefLib.getTopList()

// It is just List
// you can order, paginate it!
// https://help.bots.business/bjs/lists#getting-data 
let list = RefLib.getTopList();

// It is only for List
//   by default TopBoardLib is used
//   see useList param in track
// list.order_by = "integer_value";

// olso it is possible get newest members:
// list.order_ascending = false;

var items = list.get();
//Bot.inspect(items);

var msg = 'Top list: ';
var prop;
for(var ind in items){
  prop = items[ind]
  msg = msg + "\n" +
    String( parseInt(ind) + 1 ) + ". " + 
    CommonLib.getLinkFor(prop.user) + ": 👨" +
    String(prop.value)
}

Bot.sendMessage(msg);

How to

Q: How to give bonus to user for attracted friend?

Answer:

We can use ResourcesLib for this.

on /start

function onAttracted(refUser){
  // access to Bonus Res of refUser
  let refUserBonus = ResLib.anotherUserRes("money", refUser.telegramid);
  refUserBonus.add(100);  // add 100 bonus for friend
}

RefLib.track({
   onAttracted: onAttracted
});

Q: how to give to referrer 5% of referral user deposit?

Answer:

1. You need setup track in first

2. Seems you need use ResLib

3. On user set balance:

let res = ResLib.userRes("money");
let referrer = RefLib.getAttractedBy();

// if current user was attracted by referrer
if(referrer){
   let referrerRes = ResLib.anotherUserRes(
       "money", referrer.telegramid);
   
   let amount = res.value * 0.05; // it is 5%
   referrerRes.takeFromAnother(res, amount);
}

In this example we use userRes. Also it is possible use chatRes. See ResourcesLib for details