Документация BILLmanager 6 Startup, Advanced

Как работает реферальная программа

ISPSystem

Реферальная программа — вид сотрудничества между клиентом и провайдером, при котором клиент получает реферальную ссылку или промокод. Такой клиент считается партнёром или реферером, а новые клиенты, которые зарегистрировались по этой ссылке (промокоду) — рефералами. Партнёр получает процент от расходов своих рефералов.

Обратите внимание!

По промокоду можно привязать только нового клиента, не имеющего услуг.

Результаты реферальной программы:

  • партнёр получает прибыль за счёт привлечённых клиентов;
  • провайдер получает новых клиентов и рекламу силами партнёра.

Общая логика работы


Со стороны провайдера

Администратор панели:

  1. Создаёт реферальную программу в меню МаркетингРеферальные программы → Создать.
  2. Указывает размер вознаграждения и URL сайта провайдера.
  3. Размещает, как минимум, на одной странице сайта провайдера, следующий код:

    <script language="javascript">
      var counter_url = "https://billmgr.domain/mancgi/counter?rnd="+Math.random()+"&project=1&r="+escape(document.referrer)+"&p="+escape(window.location.href);
      document.write("<img src='" + counter_url + "' border=0 width=0 height=0 style='display: none;'>");
    </script>

    billmgr.domain — доменное имя биллинговой системы провайдера;

    rnd — параметр для предотвращения кеширования;

    project — идентификатор (id) провайдера реферальной программы. В версиях BILLmanager Startup, Advanced всегда принимает значение "1";

    r — параметр для регистрации страницы или домена, с которого перешёл реферал;

    p — полный URL текущей страницы. Из него извлекается идентификатор партнера, который привёл реферала.

    Если нужно, чтобы сайтом реферальной программы был BILLmanager, то разместите указанный код в настройках бренда. Для этого перейдите в НастройкиНастройка брендаHTML-вставкаЗаголовок.
    Этот код нужен для учёта переходов и регистраций по реферальным ссылкам.

Обратите внимание!

Один клиент может быть подключен только к одной реферальной программе.

Со стороны клиента

Клиент переходит в КлиентРеферальная программа и копирует там ссылку или промокод. Пользователи, который перешли по этой ссылке или при заказе первой услуги ввели скопированный промокод, становятся рефералами клиента.
Чтобы посмотреть статистику переходов по реферальной ссылке, клиент (реферер) переходит в меню КлиентРеферальная программаСтатистика. Меню показывает сколько раз перешли по ссылке и сколько из перешедших зарегистрировались в BILLmanager и совершили оплату.

Таблицы БД


Таблица affiliate содержит общую информацию о реферальной программе:

idnameprojectintegrationbillurlurlpromocoderewardperiodaccount_groupaccount_group_restrictname_ltname_runame_uaurl_lturl_ruurl_ua
1NULL1NULLNULLNULLLULULU@ID@1000NULLNULL8NULLRefNULLNULLhttp://172.30.20.103:8080/?p=NULL

id — код программы;

name — наименование реферальной программы;

project — код провайдера, на котором работает реферальная программа;

integration — способ применения. Не используется;

billurl — URL BILLmanager. Не используется;

url — шаблон реферальной ссылки;

promocode — шаблон реферального промокода;

reward — процент поощрения по реферальной программе;

account_group — код группы клиентов, которой доступна реферальная программа;

account_group_restrict — код группы, которой запрещено использование реферальной программы;

name_ru, name_ua — наименование реферальной программы на разных языках;

url_ru, url_uaURL сайта провайдера.

Таблица affiliateitemtype содержит информацию о награде по конкретным настроенным типам продуктов:

idaffiliateitemtypepricelistreward
11103150

id — код записи;

affiliate — код реферальной программы;

itemtype — код типа продукта;

pricelist — код тарифа;

reward — процент поощрения по реферальной программе.

Таблица account2project содержит информацию о том, к какой реферальной программе привязан клиент, чьим рефералом является и по какой реферальной программе был привлечён:

accountprojectaffiliateaffiliaterefereraffiliateprogramassigning_date
2
3
5
6
7
1
1
2
1
1
1
1
NULL
NULL
NULL
NULL
NULL
NULL
3
3
NULL
NULL
NULL
1
1
2020-01-08
2020-01-08
2020-01-10
2020-01-10
2020-01-12

account — код клиента;

project — код провайдера;

affiliateпартнёрская программа, используемая клиентом у провайдера;

affiliaterefererпартнёр, по ссылке которого привлечён клиент;

affiliateprogram — реферальная программа, по которой привлечён клиент;

assigning_date — дата подключения клиента к провайдеру.

Таблица affiliateclick содержит список переходов по реферальной ссылке:

siteaccountreferalipprojectsesidcdate



2
2
2
3
NULL
6
NULL
7
172.30.20.1
172.30.20.1
172.30.20.1
172.30.20.1
1
1
1
1
1578689949.b7XKmd
1578689962.GLQNPy
1579183750.OC4uK2
1578833311.M0DVRk
2020-01-10 20:59:09
2020-01-10 20:59:22
2020-01-16 14:09:10
2020-01-12 12:48:43

site — адрес страницы, с которой был осуществлён переход;

account — код клиента партнёра, по ссылке которого осуществлен переход;

referal — код зарегистрировавшегося по ссылке клиента;

ip — IP-адрес, с которого был осуществлён переход;

project — код провайдера, по реферальной программе которого зарегистрирован переход;

sesid — уникальный ключ;

cdate — дата и время перехода.

Таблица affiliatereward —  список начислений за реферальную программу:

idaffiliateaccountreferalamountcurrencypaymentcdateitemtypepricelistreward
11361000.000012632020-02-01NULLNULL1000

id — код записи;

affiliate — код реферальной программы, по которой совершено начисление;

account — код клиента, которому совершено начисление;

referal — код клиента, по расходам которого совершено начисление;

amount — сумма поощрения;

currency — код валюты начисления;

payment — код платежа, которым начислено поощрение;

cdate — дата начисления;

itemtype — код типа продукта, за который начислено поощрение;

pricelist — код тарифа, за который начислено поощрение;

reward — процент начисленного поощрения.

Создание реферальной программы


При создании реферальной программы BILLmanager делает запись в базу данных:

Пример записи в таблицу БД
INSERT INTO affiliate (id, name_ru, project, reward, url_ru) VALUES('1', 'Пригласи друга', '1', '15', 'http://billmanager.docker:8080/?from=')

id — id реферальной программы;

name_ru — название реферальной программы;

project — id провайдера;

reward — процент начислений от расходов реферала;

url_ru — реферальная ссылка.

При добавлении особых правил реферальной программы в меню МаркетингРеферальные программыПравилаСоздать, BILLmanager делает запись в базу данных:

Пример записи в таблицу БД
INSERT INTO affiliateitemtype (affiliate, id, itemtype, pricelist, reward) VALUES('1', '1', '103', '1', '50')

affiliate — id реферальной программы;

id — id правила;

itemtype — тип продукта;

pricelist — тарифный план;

reward — размер вознаграждения в процентах.

Переход клиента по реферальной ссылке


Учёт переходов по ссылке

При переходе по реферальной ссылке BILLmanager делает запись в базу:

Запись в таблицу БД
INSERT INTO affiliateclick (site, account, ip, project, sesid, cdate) VALUES ('', '2', '172.30.20.1', '1', '1579183750.OC4uK2', NOW())

site — адрес страницы, с которой был осуществлён переход;

account — код клиента партнёра, по ссылке которого осуществлен переход;

ip — IP-адрес, с которого был осуществлён переход;

project — код провайдера, по реферальной программе которого зарегистрирован переход;

sesid — уникальный ключ;

cdate — дата и время перехода.

Привязка реферала делается в следующих случаях:

  • при переходе на витрину;
  • вручную в настройках клиента (BILLmanager);
  • при регистрации.

Если у клиента в браузере не было сессии, реферал будет привязан, но запись  в таблице не будет создана. Такое может быть, например, при режиме инкогнито или при использовании прокси.

Логи переходов по реферальной ссылке находятся в /usr/local/mgr5/var/counter.log.

Регистрация нового клиента по реферальной ссылке

  1. Привязка клиента к провайдеру:

    Запись в таблицу БД
    INSERT INTO affiliate (id, name_ru, project, reward, url_ru) VALUES('1', 'Пригласи друга', '1', '15', 'http://billmanager.docker:8080/?from=')

    id — код программы;

    name_ru — наименование реферальной программы на русском языке;

    project — код провайдера, на котором работает реферальная программа;

    reward — процент поощрения по реферальной программе;

    url_ru — URL сайта провайдера.

  2. Подключение нового клиента к реферальной программе:

    Запись в таблицу БД
    UPDATE account2project SET affiliate='1' WHERE account='3' AND project='1'

    affiliate — партнёрская программа, используемая клиентом у провайдера;

    account — код клиента;

    project — код провайдера.

  3.  Привязка нового клиента к рефереру в качестве реферала:

    Запись в таблицу БД
    UPDATE account2project SET affiliateprogram='1', affiliatereferer='3' WHERE account='5' AND project='1'

Начисление вознаграждения


По умолчанию вознаграждения за реферальную программу начисляются по заданию в cron, первого числа каждого месяца в 3:10 по времени сервера:

Задание в cron
10 3 1 * *      /usr/local/mgr5/sbin/billmaintain --command affiliatemonthly >/dev/null 2>&1

При начислении вознаграждения за реферальную программу BILLmanager:

  1. Делает запросы для каждого реферала:

    Пример запроса
    Jan 16 12:40:16 [12:151] core_module INFO Request [billmaintain][root] 'affiliate=1&func=affiliate.process&month=2020%2D01%2D20&out=xml&referal=6&referer=2'
  2. Проверяет разрешено ли рефереру участвовать в реферальной программе:

    Пример запроса
    SELECT Count(*)
        FROM   affiliate a
           LEFT JOIN account2group a2g
                  ON a2g.account = 2
                     AND a2g.accountgroup = a.account_group
           LEFT JOIN account2group rest
                  ON rest.account = 2
                     AND rest.accountgroup = a.account_group_restrict
        WHERE  a.id = '1'
           AND ( a.account_group IS NULL
                  OR a2g.account IS NOT NULL )
           AND rest.account IS NULL


    В случае отрицательного ответа в логе будут отображаться ошибки вида:

    Пример ошибки в логе
    Jan 10 20:11:20 [2724:1586] libmgr ERROR Error: Type: 'access' Object: 'affiliate' Value: '1'
  3. Проверяет были ли уже вознаграждения за реферала за расчётный месяц:

    Пример запроса
    select count(*) from affiliatereward where account=2 and referal=6 and affiliate=1 and cdate='2020-02-01'
  4. Считает расходы реферала запросом:

    Пример запроса
    SELECT e.amount,
           s.currency,
           ai.reward,
           e.operationparams,
           ai.id AS rewardid
    FROM   subaccount s
           join expense e
             ON e.subaccount = s.id
           left join item i
                  ON i.id = e.item
           left join pricelist p
                  ON p.id = i.pricelist
           left join pricelist pparent
                  ON pparent.id = p.parent
           left join affiliateitemtype ai
                  ON ai.affiliate = 1
                     AND ( ai.pricelist IS NULL
                           AND ( ai.itemtype = p.itemtype
                                  OR ai.itemtype = pparent.itemtype )
                            OR ( ai.pricelist = p.id
                                  OR ai.pricelist = p.pricelist_group
                                  OR ai.pricelist = pparent.id
                                  OR ai.pricelist = pparent.pricelist_group )
                               AND ( ai.itemtype = p.itemtype
                                      OR ai.itemtype = pparent.itemtype ) )
           left join pricelist aip
                  ON aip.id = ai.pricelist
    WHERE  s.account = 6
           AND s.project = 1
           AND e.realdate >= '2020-01-01'
           AND e.realdate < '2020-02-01'
    ORDER  BY IF(ai.pricelist IS NULL, 0, 1) DESC,
              IF(aip.isgroup = 'on', 0, 1) DESC
  5. Если условия выполняются и у реферала есть расходы за расчётный период, начисляет рефереру вознаграждение:

    Пример записи в таблицу БД
    INSERT INTO affiliatereward (account, affiliate, amount, cdate, currency, id, referal, reward) VALUES('2', '1', '10.00', '2020-02-01', '126', '1', '6', '10')
  6. Для каждого реферера, которому было начислено вознаграждение делает запрос:

    Пример запроса
    Jan 16 12:40:16 [12:153] core_module INFO Request [billmaintain][root] 'cdate=2020%2D02%2D01&func=affiliate.createpayment&out=xml&referer=2'
  7.  Создаёт и зачисляет авансовые платежи вознаграждения с номером вида PartnerPayment/ID:

    Пример записей в БД
    INSERT INTO payment (createdate, currency, id, paymethodamount, randomnumber, status, subaccount, subaccountamount, usedamount) VALUES('2020-01-16 12:40:16', '126', '2', '10.00', 'oRBId9qgDJOr', '1', '1', '10.00', '0.0000')
       UPDATE payment SET number='PartnerPayment/2' WHERE id='2'
       UPDATE payment SET description='Авансовый платеж #2' WHERE id='2'
       UPDATE payment SET status='4' WHERE id='2'
       UPDATE payment SET description='Partner Payment - Gym' WHERE id='2'
       UPDATE affiliatereward SET payment='2' WHERE id='1'

    createdate — дата создания;

    id — код платежа;

    paymethodamount — сумма платежа в валюте метода оплаты;

    randomnumber — уникальный номер моментального платежа;

    status — текущий статус платежа:

    • 1 — новый,
    • 2 — оплачивается,
    • 3 — обещанный платёж,
    • 4 — зачислен,
    • 5 — ожидает возврата,
    • 6 — возвращён клиенту полностью,
    • 7 — мошеннический,
    • 8 — новый платёж с быстрым зачислением,
    • 100 — удаляется

    subaccount — код лицевого счета, к которому привязан платёж;

    subaccountamount — сумма платежа в валюте лицевого счета;

    usedamount — израсходованная сумма платежа;

    number — номер платежа;

    description — назначение авансового платежа;

    payment — код платежа, которым начислено поощрение.

    Обратите внимание!

    Платежи за награждение по реферальной программе создаются без указания плательщика и акты по таким платежам сделаны не будут.

Спасибо за ваш отзыв!
Была ли полезна статья?
Уточните, почему:

статья не соответствует названию

статью сложно понять

в статье нет ответа на мой вопрос

рекомендации из статьи не помогли

другая причина

Расскажите, что вам не понравилось в статье: