arb-viewer v1.0.3

ARBrowser Javascript Components

Набор javascript-компонентов для интеграции сервисов ARBrowser.

Установка и запуск демо

# get the code
git clone https://github.com/ARBrowser/js-components.git

# install dependencies
cd js-components
npm install

# run development server
npm run serve

После выполнения описанных операций демо страницу можно открыть в браузере: http://localhost:9000/

На демо странице отображается три компонента:

• кнопка просмотра в дополненной реальности (Open AR)
• 3Д вьювер
• 360 вьювер

Код демо страницы находится в файлах src/index.html и src/index.js

Как пользоваться

1. Импорт класса Viewer:

import Viewer from './viewer'

2. Создание экземпляра класса:

const viewer = new Viewer(customerKey, sku);

customerKey (string) - ключ для доступа к API ARBrowser. Для тестов необходимо использовать ключ test-customer-key. Для продакшн будет предоставлен другой ключ.

sku (string) - код товара в базе данных Эпицентр. Например, код 80335721 - это https://epicentrk.ua/ua/shop/divan-pryamoy-amf-art-metal-furniture-vizit-madras-dk-braun-1650x960x840-mm.html

Экземпляр класса должен создаваться один раз за время жизни страницы.

3. Инициализация

viewer.init(success => {
    // ...
});

Метод init выполняет асинхронную инициализацию - отправляется запрос к API ARBrowser для получения данных по товару sku. Метод принимает один параметр - callback-функцию с одним boolean аргументом success (true - инициализация прошла успешно, false - ошибка инициализации).

Инициализация должна выполняться один раз за время жизни страницы.

4. Рендеринг 3Д и 360 вьюверов

viewer.render360(selector);
viewer.render3D(selector);

selector (string) - CSS-селектор контейнера, в котором необходимо отрисовать вьювер.

Методы render360 и render3D выполняют рендеринг 360 и 3Д вьюверов соответственно в указанном контейнере. Рендеринг можно выполнять только после успешной инициализации. Методы могут вызываться несколько раз за время жизни страницы.

5. Рендеринг 360 в своем вьювере

Для рендеринга в своем вьювере можно использовать метод viewer.get360Config(), который возвращает конфигурацию 360 в таком формате:

{
  "ext": "jpg",
  "frames": 36,
  "path": "https://example.com/test-item/images/360/"
}

6. Настройка кнопки AR (просмотр в дополненной реальности)

const arButton = document.getElementById(selector);

// Show AR button
arButton.style.display = 'block';

// Setup AR button click
arButton.addEventListener('click', () => {
    if(viewer.isArSupported()) {
        viewer.openAr();
    }
    else {
        showQrCode();
    }
}, false);

Для работы с дополненной реальностью используются два метода класса Viewer:

• isArSupported: возвращает true, если устройство поддерживает AR, иначе - false
• openAr: открывает системный AR вьювер. Этот метод сработает только на устройствах, для которых метод isArSupported вернул true.

Отрисовка кнопки просмотра в дополненной реальности, окна с QR-кодом и окна подсказки не является частью компонентов ARBrowser и реализуется на стороне Эпицентра.

Рекомендуемая логика работы кнопки AR:

• изначально кнопка скрыта от пользователя
• кнопка становится видимой после того, как успешно отработал метод Viewer.init
• при клике на кнопку проверяется поддержка AR с помощью метода Viewer.isArSupported
• если AR не поддерживается - необходимо отобразить окно с QR-кодом
• если AR поддерживается:
  • если пользователю ранее уже показывали окно с подсказкой 3 либо более раз - открываем AR вьювер с помощью метода Viewer.openAr()
  • иначе показываем пользователю окно с подсказкой
  • при клике на кнопку "Начать" в окне подсказки открываем AR вьювер с помощью метода Viewer.openAr()

6. Уничтожение вьюверов

viewer.destroy();

Метод destroy уничтожает все элементы, созданные методами render360 и render3D. Может вызываться несколько раз за время жизни страницы.