React 연동

@converlay/sdk/react 엔트리 포인트는 React 애플리케이션을 위한 ConverlayProvider 컴포넌트와 useConverlay() 훅을 제공합니다. React 18 이상이 필요합니다.

ConverlayProvider

애플리케이션을 프로바이더로 감싸서 컴포넌트 트리 전체에서 Converlay 인스턴스를 사용할 수 있게 합니다.

ConverlayProvider props

<ConverlayProvider
  shopDomain="my-store.myshopify.com"  // Required
  autoPageView={true}                   // Auto page_view on mount
  debug={false}                         // Console logging
  endpoint="..."                        // Custom endpoint
  consent={{ analytics: true, marketing: true }}
>
  {children}
</ConverlayProvider>

useConverlay()

모든 하위 컴포넌트에서 Converlay 인스턴스에 접근할 수 있습니다.

useConverlay() hook

'use client'

import { useConverlay } from '@converlay/sdk/react'

function ProductPage({ product }) {
  const { track, identify, setConsent, flush, destroy } = useConverlay()

  useEffect(() => {
    track('view_item', {
      ecommerce: {
        items: [{
          item_id: product.id,
          item_name: product.title,
          price: product.price,
          quantity: 1,
        }],
      },
    })
  }, [product.id])

  return <div>{/* ... */}</div>
}

이 훅은 전체 ConverlayInstance를 반환합니다:

track(eventName, properties?)
identify(data)
setConsent(consent)
flush()
destroy()

프레임워크별 설정

Next.js App Router

클라이언트 컴포넌트 필요

프로바이더는 클라이언트 컴포넌트('use client')에 있어야 합니다. 별도의 Providers 컴포넌트를 만들어 루트 레이아웃에서 임포트하세요.

Next.js App Router

// app/providers.tsx
'use client'

import { ConverlayProvider } from '@converlay/sdk/react'

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ConverlayProvider
      shopDomain="my-store.myshopify.com"
      autoPageView={true}
    >
      {children}
    </ConverlayProvider>
  )
}

// app/layout.tsx
import { Providers } from './providers'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

Next.js Pages Router

// pages/_app.tsx
import { ConverlayProvider } from '@converlay/sdk/react'

export default function App({ Component, pageProps }) {
  return (
    <ConverlayProvider
      shopDomain="my-store.myshopify.com"
      autoPageView={true}
    >
      <Component {...pageProps} />
    </ConverlayProvider>
  )
}

Shopify Hydrogen

Hydrogen (Remix)

// app/root.tsx
import { ConverlayProvider } from '@converlay/sdk/react'

export default function App() {
  return (
    <ConverlayProvider
      shopDomain="my-store.myshopify.com"
      autoPageView={true}
    >
      <Outlet />
    </ConverlayProvider>
  )
}

라우트 변경 추적

autoPageView가 true이면 SDK는 마운트 시 page_view를 한 번 발생시킵니다. 클라이언트사이드 내비게이션(SPA)의 경우 라우트 트래커를 추가하세요:

Route tracker

'use client'

import { usePathname } from 'next/navigation'
import { useConverlay } from '@converlay/sdk/react'
import { useEffect } from 'react'

export function RouteTracker() {
  const pathname = usePathname()
  const { track } = useConverlay()

  useEffect(() => {
    track('page_view')
  }, [pathname])

  return null
}

이전← 동의 및 개인정보 보호 다음API 레퍼런스 →