The Merlin Cloud React package makes it simple for developers to connect their applications to the Merlin Cloud ecosystem. By adding a single provider, your app can automatically send user interactions and engagement data to the Merlin Cloud dashboard, while also maintaining live heartbeats to ensure performance and reliability.
This integration allows you to create rich, measurable experiences that plug directly into the insights and analytics retailers depend on.
1. Create a .npmrc file
In the root of your project, add the following:
@merlincloud:registry=https://npm.pkg.github.com //npm.pkg.github.com/:_authToken=[TOKEN]
⚠️ Note: The token shown above is a placeholder. Replace it with your own GitHub Personal Access Token with read:packages scope.
2. Install the Merlin Cloud package
npm install @merlincloud/mc-package
3. Wrap your application with the Merlin Cloud provider
In your top-level React file (e.g., App.tsx or index.tsx):
import React from "react"; import ReactDOM from "react-dom/client"; import { MerlinCloudProvider } from "@merlincloud/mc-package"; import App from "./App"; const root = ReactDOM.createRoot(document.getElementById("root") as HTMLElement); root.render( <MerlinCloudProvider environment="native"> <App /> </MerlinCloudProvider> );4. Use Merlin Cloud functions inside your components
Inside any component wrapped by MerlinCloudProvider, you can access session management and tracking:
import React from "react"; import { useMerlinSession } from "@merlincloud/mc-package"; export default function DemoComponent() { const { session, startSession, endSession, trackInteraction } = useMerlinSession(); return ( <div> <p>Session: {session ?? "No session active"}</p> <button onClick={() => startSession()}>Start session</button> <button onClick={() => trackInteraction("button_clicked")}>Track interaction</button> <button onClick={() => endSession()}>End session</button> </div> ); }5. How it works
MerlinCloudProviderlistens forwindow.postMessageevents sent from kiosks.Until a message is received, all session/interaction tracking functions stay idle.
Once triggered, you can use the exposed hooks to manage user sessions and capture analytics seamlessly within the Merlin Cloud ecosystem.