ConverlayConverlay

反应集成

@converlay/sdk/react 入口点为 React 应用程序提供了一个 ConverlayProvider 组件和一个 useConverlay() 钩子。需要 React 18 或更高版本。

传输层提供者

使用提供程序包装您的应用程序,以使 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>

使用Converlay()

从任何子组件访问 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 应用程序路由器

需要客户端组件

提供程序必须位于客户端组件 ('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 页面路由器

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 (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
}