Реферальная программа¶

У каждого пользователя есть личный реферальный код. Кто регистрируется по нему — получает бонус кредитами, и пригласивший тоже. Код и статистика отдаются одним эндпоинтом; применяется код при регистрации нового пользователя.

Свой код и статистика¶

Только для полноценного аккаунта: гостю эта ручка отвечает 403 registration_required. Закрыта именно выдача своего кода — прийти по чужому гость может, и бонусы по такой ссылке начисляются при его регистрации (см. Приглашение гостя).

curl "$BASE_URL/v1/referral" -H "Authorization: Bearer $TOKEN"

{
  "code": "AB12CD34",
  "link": "https://mivio.app/r/AB12CD34",
  "invited": 7,
  "credited": 3,
  "earned": 30
}

code — личный реферальный код (8 символов, есть у аккаунта с момента создания).
link — готовая ссылка для шаринга; в ней зашит code (формат …/r/<code>). Домен ссылки связан с приложением (universal link / app link), поэтому на устройстве с установленным приложением она открывает его и приносит код в путь; без приложения тот же адрес отдаёт веб-страницу приглашения.
invited — сколько пользователей зарегистрировались по этому коду.
credited — за скольких приглашённых начислен бонус.
earned — суммарно заработано кредитов на приглашённых.

Как применяется код¶

Отдельного запроса «ввести код» нет — реферальный код передаётся при регистрации в поле ref_code:

curl -X POST "$BASE_URL/v1/auth/register" -H 'Content-Type: application/json' \
  -d '{"email":"u@example.com","password":"s3cret","ref_code":"AB12CD34"}'

ref_code принимается в register, google, apple, vk и yandex (Аутентификация). Если пользователь пришёл по ссылке …/r/AB12CD34, клиент достаёт код из deep-link и кладёт его в ref_code при первой регистрации.

Плохой код не ломает регистрацию

Пустой, неизвестный или собственный код — тихо игнорируется (no-op): аккаунт всё равно создаётся, просто без реферальной привязки. Применить код можно только в момент регистрации — позже привязать себя к пригласившему нельзя.

Приглашение гостя¶

Основное место для кода — регистрация, и для гостя тоже. Приложение создаёт гостя при первом запуске, до того как человек что-либо ввёл, так что в этот момент кода обычно просто неоткуда взять: он появляется позже, на экране регистрации. Гость, созданный БЕЗ кода, спокойно передаёт его в register (или во вход через провайдера) с токеном гостя в заголовке — там и привязка, и бонусы.

POST /v1/auth/anonymous тоже принимает ref_code, но это случай поуже: приложение открыли по ссылке-приглашению и код известен сразу. Тогда гость связывается с пригласившим немедленно, а бонусы всё равно не платятся — они начисляются обеим сторонам, когда этот гость станет полноценным аккаунтом. Так приглашение оплачивается за живого пользователя, а не за установку приложения. Второй раз передавать код в этом случае не нужно, но и не вредно: см. ниже.

Пригласивший не подменяется

Если связь уже записана, другой код при регистрации её не перезапишет — бонус получит тот, кто привёл человека на самом деле. Так что повторная передача кода безопасна, а подменить пригласившего своим кодом на экране регистрации нельзя.

Своя ручка GET /v1/referral гостю закрыта: приглашать может тот, кто зарегистрировался сам.

Вознаграждение¶

При успешной привязке бонус кредитами начисляется обеим сторонам:

новому пользователю — за регистрацию по коду;
пригласившему — за каждого приглашённого.

Бонус не начисляется ни одной стороне, если приглашённый и пригласивший когда-либо входили с одного устройства (device_id при регистрации и входе): это один человек со вторым аккаунтом. Привязка при этом остаётся, а invited растёт, credited и earned - нет. Поэтому device_id стоит передавать всегда, когда он известен.

Начисление идемпотентно (повторная регистрация одного и того же пользователя не задвоит бонус). Обе записи видны в истории кредитов — kind referral_bonus (приглашённому) и referral_earned (пригласившему).