parcelpanel-cross-sell-tracking

v1.0.7

Published

5 months ago

Cross-sell Tracking SDK for event reporting

0High
0Medium
0Low

hubaoqing

tracking analytics cross-sell shopify sdk

Cross-sell Tracking SDK 使用指南

概述

Cross-sell Tracking SDK 提供了完整的跨应用营销解决方案：

核心SDK - 基础事件上报功能
跨应用跳转 - 支持不同APP之间的跳转链接生成
直接Query参数 - 灵活的参数传递方式
自动URL编码 - 处理所有特殊字符和中文

🚀 快速开始

1. 基础安装和初始化

import { initGlobalCrossSellTracker, CROSS_SELL_APP_KEY } from "@packages/cross-sell-tracking"

// 在应用入口处初始化
initGlobalCrossSellTracker({
  apiKey: "your-api-key",
  environment: "production",
  enableLogging: true,
  appKey: CROSS_SELL_APP_KEY.PARCEL_PANEL // 或 CROSS_SELL_APP_KEY.RETURN
})

2. 简单使用示例

const MyComponent = () => {
  const handleClick = () => {
    // 一行代码搞定：点击事件上报 + 生成跳转链接 + 打开新窗口
    window.crossSellTracker?.redirectToReturnInstall(
      "location-uuid",
      {from: "parcelpanel"}
    )
  }

  return (
    <div onClick={handleClick}>
      推荐Return应用 - 点击安装
    </div>
  )
}

📖 详细使用指南

1. 核心配置

import { CrossSellTracker, createCrossSellTracker } from "@packages/cross-sell-tracking"

// 创建实例
const tracker = createCrossSellTracker({
  apiKey: "your-api-key",
  environment: "production", // 或 "test"
  enableLogging: true,
  appKey: CROSS_SELL_APP_KEY.PARCEL_PANEL
})

// 初始化应用
await tracker.initApp({
  shopify_id: 123456,
  user_id: 789,
  domain: "store.myshopify.com",
  plan: "premium",
  shopify_version: "2024-01"
})

2. 快捷事件方法

// 浏览事件
await tracker.logViewed("location-uuid")

// 点击事件
await tracker.logClicked("location-uuid")

// 安装事件
await tracker.logInstalled("source-trace-id")

// 订阅事件
await tracker.logSubscribed("premium", 29.99)

// 发布事件（Insurance功能）
await tracker.logPublished()

// 跳转到Return安装页面（自动上报点击+生成链接+打开新窗口）
tracker.redirectToReturnInstall("location-uuid", {from: "parcelpanel"})
// 或使用字符串格式  
tracker.redirectToReturnInstall("location-uuid", "from=parcelpanel")

// 跳转到ParcelPanel安装页面（自动上报点击+生成链接+打开新窗口）
tracker.redirectToParcelPanelInstall("location-uuid", {from: "return"})
// 或使用字符串格式
tracker.redirectToParcelPanelInstall("location-uuid", "from=return")

3. 统一跳转地址配置

所有应用现在都使用统一的跳转地址，只是参数不同：

测试环境

跳转地址：https://url-test.parcelpanel.com/cs/go

生产环境

跳转地址：https://url.parcelpanel.com/cs/go

参数说明

referrer_app: 来源应用 (parcelpanel/return)
target_app: 目标应用 (return/parcelpanel)
location_uuid: 位置标识
trace_id: 跟踪ID（可选）
redirect_url: 直接包含您传递的query参数

4. 完整应用URL构建功能

跳转安装方法会自动构建完整的应用安装页面URL作为redirect_url：

参数格式支持

// 1. 对象格式（推荐）- 自动处理URL编码
tracker.redirectToReturnInstall("location-uuid", {
  from: "parcelpanel",
  utm_source: "cross_sell",
  utm_medium: "integration_card",
  utm_campaign: "2024_q4"
})

// 2. 字符串格式 - 自动重新编码确保正确性
tracker.redirectToReturnInstall("location-uuid", "from=parcelpanel&utm_source=cross_sell")

// 3. 带?的字符串格式（自动处理） - 自动编码
tracker.redirectToReturnInstall("location-uuid", "?from=parcelpanel&utm_source=cross_sell")

// 4. 无参数（只有基础应用URL）
tracker.redirectToReturnInstall("location-uuid")

生成的URL示例

// 对象格式生成的完整跳转URL：
// https://url.parcelpanel.com/cs/go?referrer_app=parcelpanel&target_app=return&location_uuid=684712eb-102a-4d5a-8432-ac45ec15c918&redirect_url=https%3A%2F%2Fapps.shopify.com%2Fparcel-panel-returns-exchanges%3Ffrom%3Dparcelpanel&trace_id=5eabc982-20e4-4785-a104-dc55f6f9d2e3

// redirect_url参数值（编码后）: https%3A%2F%2Fapps.shopify.com%2Fparcel-panel-returns-exchanges%3Ffrom%3Dparcelpanel
// redirect_url参数值（解码后）: https://apps.shopify.com/parcel-panel-returns-exchanges?from=parcelpanel

// 无参数时使用基础应用URL：
// redirect_url: https://apps.shopify.com/parcel-panel-returns-exchanges

默认应用URL

Return安装页面: https://apps.shopify.com/parcel-panel-returns-exchanges
ParcelPanel安装页面: https://apps.shopify.com/parcel-panel

重要说明

redirect_url参数：包含完整的Shopify应用商店安装页面URL
参数追加：传递的query参数会自动追加到应用URL后
编码安全：所有URL和参数都会自动进行正确的URL编码处理

🔧 实际使用场景

场景1：跨应用安装跳转（最简单）

const CrossSellInstallCard = ({ targetApp, locationUuid }) => {
  const handleInstallClick = () => {
    // 一行代码搞定跨应用安装跳转！
    if (targetApp === 'return') {
      window.crossSellTracker?.redirectToReturnInstall(
        locationUuid,
        {from: "parcelpanel", utm_source: "cross_sell_card", utm_campaign: "2024_integration"}
      )
    } else {
      window.crossSellTracker?.redirectToParcelPanelInstall(
        locationUuid,
        {from: "return", utm_source: "cross_sell_banner", utm_campaign: "tracking_feature"}
      )
    }
  }

  return (
    <div className="install-card">
      <h3>{targetApp === 'return' ? 'Return App' : 'ParcelPanel'}</h3>
      <p>点击安装体验更多功能</p>
      <button onClick={handleInstallClick}>
        立即安装
      </button>
    </div>
  )
}

场景2：应用安装追踪

import { useEffect } from "react"
import { getTraceIdFromCookie } from "@packages/cross-sell-tracking"

const AppInstallTracker = () => {
  useEffect(() => {
    // 应用安装完成后上报
    const sourceTraceId = getTraceIdFromCookie()
    window.crossSellTracker?.logInstalled(sourceTraceId)
  }, [])

  return null // 这是一个纯追踪组件
}

场景3：订阅事件追踪

const SubscriptionButton = ({ planName, planPrice }) => {
  const handleSubscribe = async () => {
    try {
      // 处理订阅逻辑
      await processSubscription()
      
      // 上报订阅成功事件
      await window.crossSellTracker?.logSubscribed(planName, planPrice)
    } catch (error) {
      console.error("订阅失败:", error)
    }
  }

  return (
    <button onClick={handleSubscribe}>
      订阅 {planName} - ${planPrice}
    </button>
  )
}

🛠️ 工具函数

Cookie管理

import { 
  getTraceIdFromCookie, 
  setTraceIdToCookie 
} from "@packages/cross-sell-tracking"

// 获取trace_id
const traceId = getTraceIdFromCookie()

// 设置trace_id (30天过期)
setTraceIdToCookie("new-trace-id", "cross_sell_trace_id", 30)

全局实例管理

import { 
  initGlobalCrossSellTracker,
  getGlobalCrossSellTracker,
  destroyGlobalCrossSellTracker
} from "@packages/cross-sell-tracking"

// 初始化全局实例
initGlobalCrossSellTracker({
  apiKey: "your-api-key",
  environment: "production"
})

// 获取全局实例
const tracker = getGlobalCrossSellTracker()

// 销毁全局实例
destroyGlobalCrossSellTracker()

📋 类型定义

// 配置接口
interface CrossSellConfig {
  apiKey: string
  environment?: "test" | "production"
  enableLogging?: boolean
  appKey?: CROSS_SELL_APP_KEY
}

// APP KEY枚举
enum CROSS_SELL_APP_KEY {
  PARCEL_PANEL = "5crtj8wVLilMPO2W4m25bq13EeoSlL6g",
  RETURN = "HILSZlKlWgM4zhk1GYjawvijNn0Eab9z",
}

// 跳转URL参数接口
interface GetRedirectUrlParams {
  target_app: string  // 目标应用
  location_uuid: string
  trace_id?: string
  redirect_url: string  // 重定向URL
  baseUrl?: string  // 可选：自定义基础URL（保留向后兼容）
}

// 事件类型
type EventType = "viewed" | "clicked" | "installed" | "subscribed" | "published"

🏗️ 最佳实践

统一初始化：在应用入口处统一初始化全局实例
错误监控：开启日志功能便于调试和监控
测试环境：开发时使用test环境，生产环境切换到production
性能考虑：合理设置曝光阈值，避免过度触发
参数传递规范：
- 确保target_app和redirect_url参数正确传递
- trace_id参数可选，不传则使用tracker内部的traceId
- 环境配置在初始化时确定，无需每次传递
- 优先使用对象格式的query参数，更清晰易维护
自定义baseUrl：
- 优先使用内置统一配置，除非有特殊需求
- 自定义baseUrl时确保URL有效且可访问
- 考虑缓存常用的自定义URL以提高性能
环境管理：
- 环境在SDK初始化时设定，后续自动使用
- 可通过getEnvironment()方法查看当前环境
- 只在特殊情况下通过targetEnvironment参数覆盖
Query参数最佳实践：
- 对象格式参数：易读易维护，支持复杂参数结构，自动处理URL编码
- 字符串格式参数：适合简单场景，SDK会自动重新编码确保正确性
- 合理使用utm_source, utm_medium, utm_campaign等标准UTM参数
- 可添加from参数标识来源应用，便于后续分析
URL编码处理：
- SDK自动处理所有特殊字符的URL编码（空格、中文、符号等）
- 对象格式参数：通过URLSearchParams自动编码，最安全
- 字符串格式参数：先解析后重新编码，确保格式正确
- 支持中文、emoji、特殊符号等任意Unicode字符
- 即使传入无效的查询字符串也会优雅处理，不会崩溃

🔗 API参考

SDK实例方法

initApp(params) - 初始化应用
logEvent(params) - 上报自定义事件
logViewed(uuid) - 上报浏览事件
logClicked(uuid) - 上报点击事件
logInstalled(sourceTraceId?) - 上报安装事件
logSubscribed(planName, planPrice) - 上报订阅事件
logPublished() - 上报发布事件
redirectToReturnInstall(locationUuid, queryParams?) - 跳转到Return安装页面
redirectToParcelPanelInstall(locationUuid, queryParams?) - 跳转到ParcelPanel安装页面
getTraceId() - 获取当前trace ID
setTraceId(traceId) - 设置trace ID
getEnvironment() - 获取当前环境配置
getRedirectUrl(params, targetEnvironment?) - 生成跨应用跳转链接

工具函数

createCrossSellTracker(config) - 创建实例
initGlobalCrossSellTracker(config) - 初始化全局实例
getGlobalCrossSellTracker() - 获取全局实例
destroyGlobalCrossSellTracker() - 销毁全局实例
getTraceIdFromCookie(cookieName?) - 从Cookie获取trace ID
setTraceIdToCookie(traceId, cookieName?, expireDays?) - 设置trace ID到Cookie

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Cross-sell Tracking SDK 使用指南

概述

🚀 快速开始

1. 基础安装和初始化

2. 简单使用示例

📖 详细使用指南

1. 核心配置

2. 快捷事件方法

3. 统一跳转地址配置

测试环境

生产环境

参数说明

4. 完整应用URL构建功能

参数格式支持

生成的URL示例

默认应用URL

重要说明

🔧 实际使用场景

场景1：跨应用安装跳转（最简单）

场景2：应用安装追踪

场景3：订阅事件追踪

🛠️ 工具函数

Cookie管理

全局实例管理

📋 类型定义

🏗️ 最佳实践

🔗 API参考

SDK实例方法

工具函数