osmos-web-sdk/README.md

OnlineSales.ai Web SDK for Vue and React projects

# OnlineSales.ai Web SDK

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

## 安装

```bash
npm install osmos-web-sdk
```

## 快速开始

### 1. 初始化SDK

```javascript
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. 获取广告

```javascript
// 获取产品页面广告
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. 跟踪事件

```javascript
// 跟踪产品查看
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 集成示例

```vue
<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 集成示例

```jsx
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也可以在浏览器中通过全局对象使用：

```html
<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