@ekolabs/eko-gallery-react
Version:
eko gallery for react framework
243 lines (177 loc) • 7.87 kB
Markdown
# Eko Gallery React
A library for integrating the [eko](https://eko.com) gallery into your react based site.
## Installation
```bash
npm install @ekolabs/eko-gallery-react
```
OR
```bash
yarn add @ekolabs/eko-gallery-react
```
## Usage
### EkoGallery Component
The `EkoGallery` component is used to render the eko gallery on your site. It should replace your existing product gallery component.
```jsx
import { EkoGallery } from '@ekolabs/eko-gallery-react';
<EkoGallery
className="mb-4"
config={config}
variantId={variantId}
activeItem={activeItem}
ref={galleryRef}
onEvent={onEkoGalleryEvent}
>
{/* Your existing product gallery component that will serve as a fallback */}
<CustomerGalley />
</EkoGallery>
```
This component accepts the following props:
| Prop | Type | Description |
| ---- | ---- | ----------- |
| className | String | _Optional._ class names to add to the `EkoGallery` component, for styling purposes for example. |
| config | Object | The eko gallery configuration. This object will be published via the eko platform and exposed via an api endpoint (see below). |
| variantId | String | _Optional._ The selected variant (if applicable). It is used to switch to the relevant variant gallery assets when the product variant changes. |
| activeItemIndex | Number | _Optional._ Updates the displayed item of the EkoGallery. |
| ref | Object | _Optional._ Exposes the next() and prev() functions that allow navigation between the steps |
| onEvent | Function | _Optional._ Handler for events occurred in the eko gallery, for third party tools tracking for example. |
> When passing the `onEvent` prop, make sure to use the `useCallback()` hook to avoid unnecessary re-renders.
### Switching the gallery's active item externally example
First, initialize a variable using React's `useRef()` hook.
Then, pass it to the `ref` property of the `EkoGallery` component.
This enables to call two functions:
1. `next()` - Will cycle to the next step of an active item. When called on the last step of an active item - the gallery will cycle to the first step of the next index.
2. `prev()` - Will cycle to the previous step of an active item. When called on the first step of an active item - the gallery will cycle to last step of the previous index.
```js
import { useRef } from 'react';
const galleryRef = useRef(null);
// Call the gallery's next() method to cycle to the next step.
function onNextClick() {
galleryRef.current.next();
}
// Call the gallery's prev() method to cycle to the previous step.
function onPrevClick() {
galleryRef.current.prev();
}
```
### Config data fetching
To get the eko product configs, you should use the `getEkoProductConfigUrl()` function to get the url, fetch the data and pass it to the `EkoGallery` component.
The `getEkoProductConfigUrl()` receives the eko sales channel id and returns the url to fetch the eko product configs from.
```js
import { getEkoProductConfigUrl } from '@ekolabs/eko-gallery-react';
const EKO_SALES_CHANNEL_ID = process.env.EKO_SALES_CHANNEL_ID;
const ekoProductConfigUrl = getEkoProductConfigUrl(EKO_SALES_CHANNEL_ID);
const ekoProductResponse = await fetch(ekoProductConfigUrl).then(res => res.json());
const ekoProductConfigs = ekoProductResponse.data;
```
### Analytics setup
Our 1st party tracking tool should be added in order to track events on the site.
#### The eko analytics snippet
The eko analytics snippet should be added to the site's head tag, here is an example in `Next.js`:
```jsx
// _document.tsx
import Script from 'next/script';
import { getEkoAnalyticsSnippet } from '@ekolabs/eko-gallery-react';
const IS_PRODUCTION = process.env.NODE_ENV === 'production';
render() {
return (
<Html lang="en">
<Head>
<Script id="eko-analytics-snippet" strategy="beforeInteractive">
{getEkoAnalyticsSnippet(IS_PRODUCTION)}
</Script>
</Head>
<body>
<Main />
<NextScript />
</body>
</Html>
);
}
```
### Events
The eko gallery dispatches events through the `onEvent` handler. Use this to track user interactions and gallery lifecycle events.
#### Event Types
| Event | Description |
| ----- | ----------- |
| `galleryinit` | Fired when the gallery component initializes |
| `gallerycoverdisplayed` | Fired when the cover image (first carousel item) loads |
| `galleryloaded` | Fired when the interactive smart gallery is fully loaded |
| `activeitemchanged` | Fired when the active gallery item changes |
| `interaction` | Fired on user interactions (clicks, scrolls, buttons, etc.) |
| `swipe` | Fired when the user swipes within the interactive video |
#### Event Payloads
##### `activeitemchanged` event
Fired when the displayed gallery item changes (via thumbnail click, carousel scroll, or internal navigation).
| Property | Type | Description |
| -------- | ---- | ----------- |
| `index` | Number | The zero-based index of the newly active item |
| `step` | Number | The zero-based index of the newly active item's step/sub-item |
##### `interaction` event
| Property | Type | Description |
| -------- | ---- | ----------- |
| `elementid` | String | A unique identifier of the element that was interacted with |
| `interactiontype` | String | The type of interaction (`click`, `wheel`, `swipe`) |
| `elementtype` | String | The type of element (e.g., `start`, `next button`, `choice button`) |
| `elementname` | String | A textual representation of the element |
Common `elementid` values from the gallery:
- `thumbnail-{index}` - Thumbnail navigation item clicked
- `nav` - Navigation strip scrolled
- `carousel` - Main carousel scrolled
- `eko-nav-arrow-prev` / `eko-nav-arrow-next` - Navigation arrows clicked
##### `swipe` event
Fired when the user swipes within the interactive video.
##### Lifecycle events (`galleryinit`, `gallerycoverdisplayed`, `galleryloaded`)
These events are fired without a payload and indicate gallery state transitions.
#### Example
```jsx
const onEkoGalleryEvent = useCallback((event, data) => {
switch (event) {
case 'galleryinit':
console.log('Gallery initialized');
break;
case 'gallerycoverdisplayed':
console.log('Cover image loaded');
break;
case 'galleryloaded':
console.log('Interactive gallery ready');
break;
case 'activeitemchanged':
console.log(`Active item changed to: ${data.index} ${data.step}`);
break;
case 'interaction':
console.log(`Interaction: ${data.elementid} (${data.interactiontype})`);
break;
case 'swipe':
console.log('User swiped in interactive video', data);
break;
}
}, []);
```
#### ekoWebPixel
The `ekoWebPixel` API is used to track the events on your site.
Init once via the `init()` method:
```jsx
import { ekoWebPixel } from '@ekolabs/eko-gallery-react';
const IS_PRODUCTION = process.env.NODE_ENV === 'production';
useEffect(() => {
ekoWebPixel.init(IS_PRODUCTION);
}, []);
```
Track events via the `track()` method:
```jsx
import { ekoWebPixel } from '@ekolabs/eko-gallery-react';
ekoWebPixel.track('pixel.page_viewed');
ekoWebPixel.track('pixel.product_viewed', { ... });
ekoWebPixel.track('pixel.cart.add', { ... });
ekoWebPixel.track('pixel.cart.remove', { ... });
// For traffic allocation:
ekoWebPixel.track('trafficallocation.decision', { ... });
// For non shopify backend stores:
ekoWebPixel.track('pixel.checkout', { ... });
ekoWebPixel.track('pixel.order', { ... });
```
Report on route changes:
```jsx
import { ekoWebPixel } from '@ekolabs/eko-gallery-react';
ekoWebPixel.onRouteChanged();
```