Интеграция с ARCoin

ARCoin является агрегатором проектов, желающих провести airdrop с использованием дополненной реальности и игровых механик в ней.

Зарегистрировать проект

В этой документации монетами называются токены или пойнты.

Алгоритм сбора монет:

1. в личном кабинете airdrop-а для пользователя генерируется ссылка на веб-страницу с AR-проектом
2. пользователь нажимает на кнопку и переходит на эту страницу
3. пользователь собирает монеты внутри дополненной реальности
4. кол-во собранных монет сохраняется на сервере ARCoin и передаётся на коллбэк
5. при достижении лимита монет открывается попап, который по нажатию возвращает на предыдущую страницу

Также пользователь может случайно найти ваши монеты в нашем приложении.

Фронтенд

В приложении или боте может быть вставлена ссылка на пространственный AR-проект (Indoor), гео-проект (Outdoor) или оба.

Некоторые приложения вставляют AR-просмотрщик прямо на страницу без перехода на новую страницу. Это обсуждается индивидуально.

Indoor

В таких проектах по умолчанию есть только одна монета - ваша.

Конкретная ссылка даётся после реализации AR-проекта. Ссылке должны быть добавлены параметры URL:

Пример ссылки на проект:

https://beta.arcoin.net/ar/?u=03lOTD7vTA0Ws65O&user_id=12345&amount=100

Подделка параметра amount повлияет только на отображение в UI. От него может зависеть кол-во 3D-объектов в сцене.

Outdoor

В гео-проектах разные монеты разбросаны случайно по планете.

Гео-проекты не имеют лимитов, но оба вида проектов имеют жёсткий лимит в 1000 кликов за сессию и др. механизмы защиты от накруток.

Общая ссылка на Outdoor:

https://beta.arcoin.net/ar/?u=3oEqJw_4_51fcL8r&user_id=1

Кнопка ARCoin

В вашем приложении должна быть вставлена кнопка с балансом ARCN пользователя и ссылкой на наше приложение. Простым вариантом является вставка готовой SVG-кнопки:

<a href="https://beta.arcoin.net/claim">
  <img src="https://beta.arcoin.net/api/airdrop/v0/balance.svg?user_id=1">
</a>

Такая кнопка не требует писать JS, не запускает чужие скрипты на вашей странице, но имеет фиксированный дизайн. Кнопка имеет ширину 150px и высоту 40px. Кнопка не будет показана (будет иметь нулевые размеры), если баланс нулевой.

Чтобы встроить баланс ARCN по-другому, нужно брать информацию о балансе из {API_URL}/balance, т.е. опустить .svg из ссылки выше. Взятие баланса ARCN не требует API-ключа.

Веб-API на нашей стороне

Коммуникация происходит при помощи http-запросов.

В документации используется базовый URL сервиса:

API_URL=https://beta.arcoin.net/api/airdrop/v0

Для обмена сообщениями используется API-ключ в заголовке Authorization. Ключ сопоставлен с монетой, поэтому а) не нужно передавать название монеты, б) нельзя поменять количество чужих монет. ARCoin хранит не сами ключи, а их хэши.

Клиент, в соответствии с RFC 7231, должен воспринимать неизвестные (обновлённые) коды статуса как код x00 соответствующего класса.

Пинг

GET {API_URL}/ping

Ответ: 200, если сервис исправен.

Получить баланс

Пользователь может собирать ваши монеты, даже если он у вас не зарегистрирован. После регистрации ваш сервер должен сделать запрос для получения баланса пользователя.

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

GET {API_URL}/balance
Authorization: Bearer API_KEY

Параметры URL:

Ответ: 200, 400, 401. Content-Type: application/json.

Веб-API на стороне партнёра

В заголовке Authorization лежит следующий токен, пример на Go:

hash := sha256.Sum256([]byte(ApiKey))
token := hex.EncodeToString(hash[:])

Баланс (веб-хук)

GET {GET_BALANCE_URL}
Authorization: Bearer sha256(API_KEY)

Параметры URL:

Ответы: 200 (ок), 404 (пользователь не найден). Content-Type: application/json.

Коллбэк поступления монет (веб-хук)

Наш сервер отправляет число кликов в текущей сессии, если оно больше нуля. Вызывается, когда пользователь закрыл AR-проект, а также периодически не чаще раза в минуту. Это количество будет сохранено в нашу БД.

Наш сервер отправляет кол-во собранных монет, даже если у вас такой пользователь ещё не зарегистрирован. Вы можете игнорировать эти запросы и взять баланс в момент его регистрации или создавать пользователя и собирать данные сразу.

POST {CHANGE_BALANCE_URL}
Authorization: Bearer sha256(API_KEY)
Content-Type: application/json

Параметры запроса:

Ответы: 200 (ок), 404 (пользователь не найден). Content-Type: application/json.

Пример тела запроса:

{
    "user_id": 1,
    "amount": 25,
    "coin": "BONK"
}

Пример ответа:

{
    "available_coins": 15
}