OnlineSales.ai Web SDK

一个用于Vue和React项目的JavaScript SDK，用于集成OnlineSales.ai的广告和跟踪功能。

安装

npm install osmos-web-sdk

快速开始

1. 初始化SDK

import { OsmosSDK } from 'osmos-web-sdk';

const osmos = new OsmosSDK();
osmos.initialize({
  clientId: YOUR_CLIENT_ID,
  productAdsHost: "api.onlinesales.ai",
  displayAdsHost: "brand-api.onlinesales.ai",
  debugMode: true // 开发时启用调试模式
});

2. 获取广告

// 获取产品页面广告
const productAds = await osmos.adFetcher.fetchPLAProductPageAds({
  cliUbid: "user_123",
  skuIds: ["LAPTOP123"],
  productCount: 3
});

// 获取搜索页面广告
const searchAds = await osmos.adFetcher.fetchPLASearchPageAds({
  cliUbid: "user_456",
  keyword: "wireless headphones",
  productCount: 4
});

// 获取展示广告
const displayAds = await osmos.adFetcher.fetchDisplayAds({
  cliUbid: "user_789",
  pageType: "CATEGORY",
  adUnit: ["HEADER_BANNER", "SIDEBAR_AD"],
  productCount: 2
});

3. 跟踪事件

// 跟踪产品查看
await osmos.tracking.trackProductView("LAPTOP123");

// 跟踪添加到购物车
await osmos.tracking.trackAddToCart("LAPTOP123", 1);

// 跟踪购买
await osmos.tracking.trackPurchase(["LAPTOP123", "MOUSE456"], 1299.99);

// 跟踪广告点击
await osmos.tracking.trackAdClick("ad_123", "HEADER_BANNER");

配置选项

必需参数

• clientId: 客户端ID（由OnlineSales.ai提供）
• productAdsHost: 产品广告服务器主机名
• displayAdsHost: 展示广告服务器主机名

可选参数

• eventTrackingHost: 事件跟踪服务器主机名
• cliUbid: 客户端生成的唯一浏览器ID
• device: 设备类型（'MOBILE', 'TABLET', 'DESKTOP'）
• enableTracking: 是否启用事件跟踪（默认：true）
• debugMode: 是否启用调试模式（默认：false）

API 参考

广告获取方法

fetchDisplayAds(query)

获取展示广告

fetchPLAProductPageAds(query)

获取产品页面广告

fetchPLASearchPageAds(query)

获取搜索页面广告

fetchPLACategoryPageAd(query)

获取分类页面广告

fetchPLATPAPageAd(query)

获取TPA页面广告

fetchPLAPurchasePageAd(query)

获取购买页面广告

fetchPLAHomePageAd(query)

获取首页广告

fetchPLACustomPageAd(query)

获取自定义页面广告

跟踪方法

trackProductView(skuId, additionalData?)

跟踪产品查看事件

trackAddToCart(skuId, quantity?, additionalData?)

跟踪添加到购物车事件

trackPurchase(skuIds, total, additionalData?)

跟踪购买事件

trackAdClick(adId, adUnit, additionalData?)

跟踪广告点击事件

trackVideoView(videoId, duration, additionalData?)

跟踪视频观看事件

trackSearch(keyword, resultsCount?, additionalData?)

跟踪搜索事件

trackPageView(pageName, additionalData?)

跟踪页面浏览事件

Vue.js 集成示例

<template>
  <div>
    <div v-if="ads.length > 0">
      <div v-for="ad in ads" :key="ad.id" class="ad-item">
        <img :src="ad.image" :alt="ad.title" />
        <h3>{{ ad.title }}</h3>
        <p>{{ ad.price }}</p>
        <button @click="handleAdClick(ad)">查看详情</button>
      </div>
    </div>
  </div>
</template>

<script>
import { OsmosSDK } from 'osmos-web-sdk';

export default {
  name: 'ProductAds',
  data() {
    return {
      osmos: null,
      ads: []
    };
  },
  async mounted() {
    // 初始化SDK
    this.osmos = new OsmosSDK();
    this.osmos.initialize({
      clientId: YOUR_CLIENT_ID,
      productAdsHost: "api.onlinesales.ai",
      displayAdsHost: "brand-api.onlinesales.ai"
    });

    // 获取广告
    await this.loadAds();
  },
  methods: {
    async loadAds() {
      try {
        const response = await this.osmos.adFetcher.fetchPLAProductPageAds({
          cliUbid: "user_123",
          skuIds: ["LAPTOP123"],
          productCount: 3
        });

        if (response.success) {
          this.ads = response.data;
        }
      } catch (error) {
        console.error('Failed to load ads:', error);
      }
    },
    async handleAdClick(ad) {
      await this.osmos.tracking.trackAdClick(ad.id, "PRODUCT_RECOMMENDATION");
      // 处理广告点击逻辑
    }
  }
};
</script>

React 集成示例

import React, { useState, useEffect } from 'react';
import { OsmosSDK } from 'osmos-web-sdk';

const ProductAds = () => {
  const [osmos, setOsmos] = useState(null);
  const [ads, setAds] = useState([]);

  useEffect(() => {
    // 初始化SDK
    const sdk = new OsmosSDK();
    sdk.initialize({
      clientId: YOUR_CLIENT_ID,
      productAdsHost: "api.onlinesales.ai",
      displayAdsHost: "brand-api.onlinesales.ai"
    });
    setOsmos(sdk);

    // 加载广告
    loadAds(sdk);
  }, []);

  const loadAds = async (sdk) => {
    try {
      const response = await sdk.adFetcher.fetchPLAProductPageAds({
        cliUbid: "user_123",
        skuIds: ["LAPTOP123"],
        productCount: 3
      });

      if (response.success) {
        setAds(response.data);
      }
    } catch (error) {
      console.error('Failed to load ads:', error);
    }
  };

  const handleAdClick = async (ad) => {
    await osmos.tracking.trackAdClick(ad.id, "PRODUCT_RECOMMENDATION");
    // 处理广告点击逻辑
  };

  return (
    <div>
      {ads.length > 0 && (
        <div className="ads-container">
          {ads.map(ad => (
            <div key={ad.id} className="ad-item">
              <img src={ad.image} alt={ad.title} />
              <h3>{ad.title}</h3>
              <p>{ad.price}</p>
              <button onClick={() => handleAdClick(ad)}>查看详情</button>
            </div>
          ))}
        </div>
      )}
    </div>
  );
};

export default ProductAds;

浏览器全局对象

SDK也可以在浏览器中通过全局对象使用：

<script src="https://c.o-s.io/osmos-web-sdk/sdk.js"></script>
<script>
  // 初始化
  osmos.initialize({
    clientId: YOUR_CLIENT_ID,
    productAdsHost: "api.onlinesales.ai",
    displayAdsHost: "brand-api.onlinesales.ai"
  });

  // 获取广告
  osmos.adFetcher.fetchPLAProductPageAds({
    cliUbid: "user_123",
    skuIds: ["LAPTOP123"],
    productCount: 3
  }).then(response => {
    if (response.success) {
      console.log('Ads loaded:', response.data);
    }
  });

  // 跟踪事件
  osmos.tracking.trackProductView("LAPTOP123");
</script>

许可证

MIT License