trillion-widget/README.md

Trillion AR Widget

# Trillion AR Widget

This is Trillion AR Widget that allow you to integrate Trillion SDK in your site. For more information please visit https://trillion.jewelry

## Installing

Using npm:

```shell
npm install trillion-widget
```

Using yarn:

```shell
yarn add trillion-widget
```

## How to use:
First of all **get your API key** from https://dashboard.trillion.jewelry/integration

Then you need to create an empty div element for widget initialization.
For example:

```html
 <div id="trillion-widget"></div>
```

Then, in your js code (**don't forget to set your API key**):

```js
import {TrillionWidgetApp} from "trillion-widget"

const elem = document.getElementById('trillion-widget')
const trillionWidget = new TrillionWidgetApp()
trillionWidget.init(elem)
trillionWidget.setServiceActivationKey("YOUR_API_KEY_HERE")
trillionWidget.setJewelryID('demo-pendant-ar')
trillionWidget.setJewelryType('necklace')
trillionWidget.refresh()
```

For typescript:

```ts
const elem = document.getElementById('trillion-widget') as HTMLElement
```

## Instance methods

* `trillionWidget#init()` - Create widget on the provided HTML element
* `trillionWidget#setServiceActivationKey(KEY)` - Set API key for app
* `trillionWidget#refresh()` - reload widget after changing parameters
* `trillionWidget#setWidgetMode(mode)` - Set widget mode (basic, ring_carousel, two_hands)
* `trillionWidget#getWidgetMode(mode)` - Get current widget mode
* `trillionWidget#setJewelryID(sku)` - Set the id(SKU) of the jewelry to load
* `trillionWidget#getJewelryID()` - Get the id(SKU) of the uploaded jewelry
* `trillionWidget#setCarousel(sku[])` - Set a group of jewelry. 
 If set, the widget shows selector with all elements of the group and ignores jewelry from setJewelryID
 By default, widget will load first element of the group
* `trillionWidget#getCarousel()` - Get a group of jewelry
* `trillionWidget#setJewelryType(type)` - Set the jewelry type (earrings, ring, necklace) to load. *Deprecated, type will be detected automatically*
* `trillionWidget#getJewelryType()` - Get the uploaded jewelry type. *Deprecated, type will be detected automatically*
* `trillionWidget#setUsePerformanceCheck(use)` - use performance check
* `trillionWidget#getUsePerformanceCheck()` - get performance check
* `trillionWidget#setLanguage(language)` - set language. Available languages: 'en', 'kr', 'ru'
* `trillionWidget#getLanguage()` - get language
* `trillionWidget#useExternalUi()` - Hide native UI
* `trillionWidget#getScreenshot()` - Get screenshot

## Ring carousel
Setting up the carousel mode:
```js
trillionWidget.setWidgetMode("ring_carousel") // Enables carousel mode
trillionWidget.setCarousel(["ring-sku-1", "ring-sku-2", "..."]) // Sets the SKUs of rings used
```

### Custom
If you want to control switching between carousel items yourself, you can hide the native UI and manually update the currently selected carousel item.
For example:
```js
trillionWidget.useExternalUi(true)
trillionWidget.refresh()

customButton1.addEventListener('click', () => {
  trillionWidget.updateCarouselItem('ring-sku-1')
})
customButton2.addEventListener('click', () => {
  trillionWidget.updateCarouselItem('ring-sku-2')
})
```

## Using CDN to get Trillion Widget

use this pattern:
`unpkg.com/:package@:version/:file`

For example:

```js
import {TrillionWidgetApp} from "https://sdk.trillion.jewelry/widget/latest/trillion-widget.js"
```

## React component

This library also provides the React component for widget.

### How to use

import component:
```js
import { TrillionWidget, JewelryTypeName } from "trillion-widget";
```

use somewhere in your React application:

```js
function MyComponent() {
  return (
    <div className="MyComponent">
        <TrillionWidget jewelryId={'demo-earrings'} jewelryType={JewelryTypeName.Earrings}/>
    </div>
  )
}
```