此功能当前处于白名单阶段，如有需要请联系客户经理开通。
概述
SHOPLINE 像素 API
SHOPLINE 提供了像素 API，用于访问浏览器 API 并订阅客户事件，这些功能会在沙箱环境中加载。
通过 SHOPLINE 像素 API，开发者可以收集并传递客户行为数据，以进行市场营销和分析。
关于应用像素 API
应用像素是作为第三方应用或销售渠道的一部分安装的脚本，由应用开发者创建，在严格的沙箱环境中运行，使用SHOPLINE官方的像素API来收集或检索数据，从而减少对您网站整体性能、安全性和隐私的影响。
SHOPLINE仅将使用SHOPLINE像素API的应用添加到客户事件页面。应用需要先安装，然后进行设置以配置像素。
import {configure} from "@shoplineos/shopline-pixels-extension";
configure((api) => {
// subscribe page view event example
api.analytics.subscribe("page_viewed", (event) => {
console.log("pixel page_viewed", event);
fetch("https://example.com", {
method: "POST",
body: JSON.stringify(event)
});
});
});
关于自定义像素
自定义像素代码在宽松的沙盒环境中加载，并通过SHOPLINE后台的像素管理器界面进行配置。在此开发者界面中，像素API已为您解构完毕，您无需编写任何额外的样板代码即可直接调用。
请注意：自定义像素代码需要连接后才会生效。
// subscribe page view event example
analytics.subscribe("page_viewed", (event) => {
console.log("pixel page_viewed", event);
fetch("https://example.com", {
method: "POST",
body: JSON.stringify(event)
});
});
参数说明
基本参数
1. clientIId：SHOPLINE提供的用户唯一id;
2. context：上报事件的浏览器相关信息
2.1. document：当前浏览器document对象上的快照信息
2.1.1. characterSet：编码格式
2.1.2. location：当前URL
2.1.3. referer：来源页面地址URL
2.1.4. title：页面名称
2.2. navigator：当前浏览器navigator对象上的快照信息
2.2.1. cookieEnable：放回false如果cookie被关闭
2.2.2. language：用户首选语言
2.2.3. languages：按偏好顺序返回表示用户已知语言的字符串数组
2.2.4. userAngent：浏览器用户代理
2.3. window：当前浏览器window对象上的快照信息
2.3.1. innerHeight：获取浏览器窗口内容区域的高度，包括水平滚动条（如果呈现）;
2.3.2. InnerWidth：获取浏览器窗口内容区域的宽度，包括垂直滚动条（如果呈现）;
2.3.3. location：当前URL
2.3.4. origin：全局对象的起源，序列化为字符串
2.3.5. outerHeight：获取以像素为单位指定窗口的外部高度
2.3.6. outerWidth：获取以像素为单位指定窗口的外部宽度
2.3.7. pageXOffset：window.scrollX 的别名
2.3.8. pageYOffest：window.scrollY 的别名
2.3.9. screenX：获取窗口距离屏幕左边界的像素长度
2.3.10. screenY：获取窗口距离屏幕上边界的像素长度
2.3.11. scrollX：获取文档水平滚动的像素
2.3.12. scrollY：获取文档垂直移动的像素
3. data：根据不同的事件上报的事件内容
4. id：上报事件的唯一标识
5. name：上报事件的名称
6. timestamp：上报事件的时间戳
interface BasePixelPayload {
clientId: ClientId;
context: Context;
id: Id;
timestamp: Timestamp;
}
export type ClientId = string;
export type Id = string;
export type Timestamp = string;
公共参数
-
login_em: 用户登录的邮箱
-
customer_id: SHOPLINE提供的唯一买家账户ID。
interface EventCommonPayload {
login_em: string | null;
customer_id: string | null;
}
自定义事件说明
1. 在线商店发送事件
OnlineStore（前端代码/可以是自定义代码）
const event_name = 'my_custom_event';
const event_data = {test: "this is test!"};
/**
* @param: event_name
* @param: event_data
*
*/
Shopline.analytics.publish(event_name, event_data)
2. 使用方式
- CustomPixel：
analytics.subscribe('my_custom_event', (event) => {
console.log('my_custom_event', event)
});
- App Pixel：
import {configure} from "@shoplineos/shopline-pixels-extension";
configure((api) => {
api.analytics.subscribe('my_custom_event', (event) => {
console.log('my_custom_event', event)
});
});
标准事件说明
1. lead - 询盘
事件定义：提交询盘申请
export interface LeadPayload extends EventCommonPayload {
currency: string;
list: {
spuId?: string; // 商品 SpuId
skuId?: string; // 商品 SkuId
skuItemNo?: string; // 商品货号
title?: string; // 商品名称
price: number; // 商品价格
category?: string; // 商品类目
}[];
}
export interface PixelEventsLead {
data: LeadPayload;
name: 'lead';
}
2. registration_complete - 注册
事件定义：注册成功之后上报
export interface RegistrationCompletedPayload extends EventCommonPayload {
method: string; //注册方式，枚举值：Facebook/Google/Email/Phone
email?: string;
phone?: string;
user_id: string; //uid,Shopline的用户唯一标识
}
export interface PixelEventsRegistrationCompleted {
data: RegistrationCompletedPayload;
name: 'login';
}
3. login - 登录
事件定义：登录成功信息回传时候上报
export interface LoginPayload extends EventCommonPayload {
method: string; //登陆方式
}
export interface PixelEventsLogin {
data: LoginPayload;
name: 'login';
}
4. search_submitted -提交搜索
事件定义：点击搜索按钮或者其他方式成功提交。
当顾客在前端商店搜索产品时，会记录search_submitted事件。该事件可在网店页面获取。搜索查询返回的产品会包含在此事件对象中（数组中列出的每个产品的首个变体）。该事件可在网店页面获取。
export interface SearchSubmitPayload extends EventCommonPayload {
keyword: string; // 搜索关键字
}
export interface PixelEventsSearchSubmitted {
data: SearchSubmitPayload;
name: 'search_submitted';
}
5. search_view_results - 搜索结果曝光
事件定义：当客户查看搜索结果页面时，search_view_results 事件会触发。
export interface SearchViewResultsPayload extends EventCommonPayload {
keyword: string; // 搜索关键字
currency: string;
// 商品列表
list: {
spuId: string; // 商品 SpuId
skuId: string; // 商品 SkuId
skuItemNo: string; // 商品货号
title: string; // 商品名称
price: number; // 商品价格
category: string; // 商品类目
}[];
}
export interface PixelEventsSearchViewResults {
data: SearchViewResultsPayload;
name: 'login';
}
6. page_viewed -页面曝光
事件定义：当客户浏览网站上的特定页面时，page_viewed事件会记录该实例。此事件适用于在线商店、产品、结账和订单页面。
export interface PageViewPayload extends EventCommonPayload {
title: string; // the title of the current page
url: string; // the URL of the current page
path: string;
}
export interface PixelEventsPageViewed {
data: PageViewPayload;
name: 'page_viewed';
}
7. product_viewed -查看商品详情
事件定义：当客户访问产品详情页面时。
export interface ProductViewPayload extends EventCommonPayload {
spuId: string; // 商品 SpuId
skuId: string; // 商品 SkuId
skuItemNo: string; // 商品货号
currency: string;
title: string; // 商品名称
variant: string; // 商品 Sku variant
price: number; // 商品价格
category: string; // 商品类目
collectionId: string; // 商品分类 Id
collectionName: string; // 商品分类名称
}
export interface PixelEventsProductViewed {
data: ProductViewPayload;
name: 'product_viewed';
}
8. collection_viewed -查看商品列表
事件定义：当顾客浏览产品系列页面时。
export interface CollectionViewedPayload extends EventCommonPayload {
collectionType: IProductListCollectionType; // 列表页类型
collectionId: string; // 商品分类 Id
collectionName: string; // 商品分类名称
currency: string;
// 商品列表
list: {
spuId: string; // 商品 SpuId
skuId: string; // 商品 SkuId
skuItemNo: string; // 商品货号
title: string; // 商品名称
price: number; // 商品价格
category: string; // 商品类目
}[];
}
export interface PixelEventsCollectionViewed {
data: CollectionViewedPayload;
name: 'collection_viewed';
}
9. product_added_to_cart -商品加入购物车
事件定义：在商品详情页、列表页、首页通过点击加购按钮把 sku 加入到购物车，或者在购物车页增加件数，在其他页面使用接口完成加购事实的，也包含在内
export interface ProductAddToCartPayload extends EventCommonPayload {
cartId: string;
value: number; // 加购金额
currency: string;
// 加购商品列表
list: {
spuId: string; // 商品 SpuId
skuId: string; // 商品 SkuId
skuItemNo: string; // 商品货号
title: string; // 商品名称
variant: string; // 商品 Sku variant
price: number; // 商品价格
quantity: number; // 加购数量
category: string; // 商品类目
}[];
}
export interface PixelEventsProductAddedToCart {
data: ProductAddToCartPayload;
name: 'product_added_to_cart';
}
10. product_removed_from_cart - 从购物车移除商品
事件定义：在购物车页移除商品或者减少件数或者在其他页面使用接口完成上述事实的
export interface ProductRemovedFromCartPayload extends EventCommonPayload {
cartId: string;
value: number; // 减少金额
currency: string;
// 减少商品列表
list: {
spuId: string; // 商品 SpuId
skuId: string; // 商品 SkuId
skuItemNo: string; // 商品货号
title: string; // 商品名称
variant: string; // 商品 Sku variant
price: number; // 商品价格
quantity: number; // 减少数量
category: string; // 商品类目
}[];
}
export interface PixelEventsProductRemovedFromCart {
data: ProductRemovedFromCartPayload;
name: 'product_removed_from_cart';
}
11. cart_viewed -查看购物车
事件定义：购物车页曝光购物车抽屉窗口曝光
export interface CartViewPayload extends EventCommonPayload {
currency: string; // 前端可见币种
value: number; // 购物车总金额
// 购物车有效的商品列表
list: {
spuId: string; // 商品 SpuId
skuId: string; // 商品 SkuId
skuItemNo: string; // 商品货号
title: string; // 商品名称
variant: string; // 商品 Sku variant
price: number; // 商品价格
quantity: number; // 加购数量
category: string; // 商品类目
}[];
}
export interface PixelEventsCartViewed extends BasePixelPayload {
name: 'cart_viewed';
data: CartViewPayload;
}
12. checkout_started -开始结账
事件定义：顾客开始结账流程。该事件在结账页面触发。
export interface CheckoutStartedPayload extends EventCommonPayload {
value: number;
currency: string;
list: {
spuId: string;
skuId: string;
skuItemNo: string;
title: string;
variant: string;
price: number;
quantity: number;
category: string;
}[];
}
export interface PixelEventsCheckoutStarted {
data: CheckoutStartedPayload;
name: 'checkout_started';
}
13. checkout_contact_info_submitted - 结账提交联系信息
事件定义：当客户成功提交联系信息表单时。该事件会在单页结账场景中客户成功提交结账表单时记录。
export interface CheckoutContactInfoSubmittedPayload extends EventCommonPayload {
value: number;
currency: string;
email?: string;
phone?: string;
shippingAddress: Partial<{
address1: string;
address2: string;
city: string;
country: string;
firstName: string;
lastName: string;
phone: string;
state: string;
zip: string;
}>;
list: {
spuId: string;
skuId: string;
skuItemNo?: string;
title: string;
variant: string;
price: number;
quantity: number;
category?: string;
}[];
}
export interface PixelEventsCheckoutContactInfoSubmitted {
data: CheckoutContactInfoSubmittedPayload;
name: 'checkout_contact_info_submitted';
}
14. payment_info_submitted -提交支付信息
事件定义：支付信息提交事件记录客户成功提交支付信息的实例。此事件可在结账页面上触发。
export interface PaymentInfoSubmittedPayload extends EventCommonPayload {
value: number;
paymentType: string; // 支付渠道
productPrice: number;
currency: string;
list: {
spuId: string;
skuId: string;
skuItemNo: string;
title: string;
variant: string;
price: number;
quantity: number;
category: string;
}[];
}
export interface PixelEventsPaymentInfoSubmitted {
data: PaymentInfoSubmittedPayload;
name: 'payment_info_submitted';
}
15. checkout_completed -完成结账
事件定义：成单，在线支付方式为支付成功后成单、线下支付为提交订单后成单。
export interface CheckoutCompletedPayload extends EventCommonPayload {
orderSeq: string;
appOrderSeq: string;
value: number;
shippingAmount: number;
taxAmount: number;
coupon?: string;
currency: string;
list: {
spuId: string;
skuId: string;
skuItemNo: string;
title: string;
variant: string;
price: number;
quantity: number;
category: string;
}[];
}
export interface PixelEventsCheckoutCompleted {
data: CheckoutCompletedPayload;
name: 'checkout_completed';
}