Hướng dẫn sử dụng Widget SDK

Hướng dẫn cập nhật Widget SDK

Bài viết này ghi lại các thay đổi đối với SDK <Widget>.

@tiktokshop/widget-kit

Dành cho tích hợp js thuần (native js)

<Version 1.0.2>

Ngày phát hành: 2024/2/19

Đã sửa một số lỗi.

<Version 1.0.0>

Added

modules	description
init	Thêm phương thức init để hỗ trợ người dùng tích hợp và khởi tạo widget.
loadWidget	Thêm phương thức loadWidget để hỗ trợ người dùng tải trang widget của chúng tôi.
update	Thêm phương thức update để hỗ trợ người dùng chỉnh sửa cấu hình widget.
preloadWidget	Thêm phương thức preloadWidget để hỗ trợ người dùng tải trước (preload) tài nguyên widget.

@tiktokshop/widget-kit-react

Dành cho tích hợp component React

<Version 1.0.2>

Ngày phát hành: 2024/2/19

Added

modules	description
WidgetConfigProvider	Thêm component WidgetConfigProvider, component này tích hợp các phương thức init, update, preload ban đầu. WidgetConfigProvider nên được dùng cùng với RemoteWidget; trong kịch bản tích hợp react, khuyến nghị sử dụng WidgetConfigProvider thay vì gọi trực tiếp init, update, preload.
RemoteWidget	Thêm component RemoteWidget. Phương thức loadWidget ban đầu được tích hợp bên trong component. Cung cấp sẵn placeholder cho trạng thái đang tải và placeholder cho trạng thái bất thường. Người dùng có thể chỉ định widget, tải tài nguyên và render component theo tên. RemoteWidget nên được dùng cùng với WidgetConfigProvider. Trong kịch bản tích hợp react, khuyến nghị sử dụng RemoteWidget thay vì gọi trực tiếp loadWidget.

modules

description

WidgetConfigProvider

Thêm component WidgetConfigProvider, component này tích hợp các phương thức init, update, preload ban đầu. WidgetConfigProvider nên được dùng cùng với RemoteWidget; trong kịch bản tích hợp react, khuyến nghị sử dụng WidgetConfigProvider thay vì gọi trực tiếp init, update, preload.

RemoteWidget

Thêm component RemoteWidget. Phương thức loadWidget ban đầu được tích hợp bên trong component. Cung cấp sẵn placeholder cho trạng thái đang tải và placeholder cho trạng thái bất thường. Người dùng có thể chỉ định widget, tải tài nguyên và render component theo tên. RemoteWidget nên được dùng cùng với WidgetConfigProvider. Trong kịch bản tích hợp react, khuyến nghị sử dụng RemoteWidget thay vì gọi trực tiếp loadWidget.

<Version 1.0.0>

Added

modules	description
init	Thêm phương thức init để hỗ trợ người dùng tích hợp và khởi tạo widget.
loadWidget	Thêm phương thức loadWidget để hỗ trợ người dùng tải trang widget của chúng tôi.
update	Thêm phương thức update để hỗ trợ người dùng chỉnh sửa cấu hình widget.
preloadWidget	Thêm phương thức preloadWidget để hỗ trợ người dùng tải trước (preload) tài nguyên widget.

Bắt đầu nhanh

Cấu hình môi trường phát triển

Thích ứng framework

Chúng tôi hỗ trợ hai phương thức tích hợp: tích hợp framework react và tích hợp js thuần (native js). Người dùng sử dụng framework react có thể tích hợp bằng phương thức component react, còn người dùng không dùng framework react có thể tích hợp bằng phương thức JS thuần.

Cài đặt các dependency

Để sử dụng tích hợp component react, vui lòng cài đặt các package sau:

JSONWord Wrap

npm install @tiktokshop/widget-kit-react

Để tích hợp js thuần, vui lòng cài đặt các package sau:

JSONWord Wrap

npm install @tiktokshop/widget-kit

Tích hợp SDK

Điều kiện tiên quyết

Máy chủ cần phát triển một API để lấy token ngắn hạn (tham khảo tài liệu Get Widget Token để biết phương thức phát triển). Khi front-end tích hợp trang widget, trong giai đoạn khởi tạo SDK, trường getWidgetToken được truyền vào hàm để lấy token.
Vì lý do bảo mật, có các giới hạn cross-origin đối với các interface trong trang widget. Khi tích hợp widget, bạn cần cung cấp tên miền cho nền tảng mở (open platform) để cấu hình whitelist.

Sử dụng cho framework react (khuyến nghị):

Khuyến nghị đặt WidgetConfigProvider ở lớp ngoài cùng của toàn bộ ứng dụng để cấu hình thống nhất toàn cục

TYPESCRIPTWord Wrap

import { WidgetConfigProvider } from '@tiktokshop/widget-kit-react';  
  
const initOptions =  {  
    config:{  
      shopId: 'xxx', //seller id, such as 123456  
      oecRegion: 'xxx',//country,such as US  
      appKey: 'xxx',//The key corresponding to the merchant's creation service  
      isvInfo: {  
        name: 'xxx',//ISV name,such as OPEN_PLATFORM  
      },  
    },  
    getToken:getWidgetToken,  
    // If you integrate multiple widgets, remotes can set multiple  
    remotes:[  
    {  
      name: 'xxx',//Integrated business name, provided by the open platform,such as:@tiktokshop-widget/product:optimizer  
    },  
  ]  
};  
  
export default () => {  
  return (  
    <WidgetConfigProvider  
        config={initOptions.config}   
        getToken={initOptions.getToken}   
        remotes={initOptions.remotes}  
        preloadWidgetNames={['@tiktokshop-widget/product:optimizer']}   
    >  
      <RemoteWidget   
        name={'@tiktokshop-widget/product:optimizer'}   
        className={'containerClass'}   
        options={{}}  
      />  
    </WidgetConfigProvider>  
  );  
};

Sử dụng JS thuần:

TYPESCRIPTWord Wrap

import { init } from '@tiktokshop/widget-kit';  
  
init({  
  config: {  
      shopId: 'xxx', //seller id, such as 123456  
      oecRegion: 'xxx',//country,such as US  
      appKey: 'xxx',//The key corresponding to the merchant's creation service  
      isvInfo: {  
        name: 'xxx',//ISV name,such as OPEN_PLATFORM  
      },  
    },  
  remotes: [  
    {  
      name: 'xxx',//Integrated business name, provided by the open platform,such as:@tiktokshop-widget/product:optimizer  
    },  
  ],  
  getToken: getWidgetToken,//get auth token  
});

Nếu trang widget không hiển thị ở màn hình đầu tiên, tài nguyên có thể được tải trước (preload), điều này giúp giảm thời gian tải của các component sau và cải thiện tốc độ phản hồi của trang.

Sử dụng cho framework react:

Cấu hình preload trong preloadWidgetNames của WidgetConfigProvider, bạn có thể đặt WidgetConfigProvider ở lớp ngoài cùng để preload

JSONWord Wrap

// For react component integration  
import { preloadWidget } from '@tiktokshop/widget-kit-react';  
  
export default () => {  
  return (  
    <WidgetConfigProvider  
        config={initOptions.config}   
        getToken={initOptions.getToken}   
        remotes={initOptions.remotes}  
        preloadWidgetNames={['@tiktokshop-widget/product:optimizer']}   
    >  
      <RemoteWidget   
        name={'@tiktokshop-widget/product:optimizer'}   
        className={'containerClass'}   
        options={{}}  
      />  
    </WidgetConfigProvider>  
  );  
};

Sử dụng JS thuần:

Tải trước bằng preloadWidget

JSONWord Wrap

// For native js integration  
import { preloadWidget } from '@tiktokshop/widget-kit';//Reference method depends on the selected integration scheme  
  
preloadWidget(['@tiktokshop-widget/product:optimizer']);

Sử dụng cho framework react:

JAVASCRIPTWord Wrap

import { RemoteWidget } from "@tiktokshop/widget-kit-react";  
  
const name = "@tiktokshop-widget/product:optimizer";  
  
export function Test() {  
  return <RemoteWidget   
      name={name}   
      className={'widget-preview-container'}   
      options={{}}  
    />;  
}

Sử dụng JS thuần:

JSONWord Wrap

import { loadWidget, WidgetComponent } from '@tiktokshop/widget-kit';  
  
//load widget  
const name = '@tiktokshop-widget/product:optimizer';  
let view = null;  
loadWidget(name).then((component: WidgetComponent) => {  
  view = component.create(  
    document.getElementById('widget-preview-container')!,  
  );  
  view?.render({});  
});  
  
//create a mount element  
<div  
  className="widget-preview-container"  
  id="widget-preview-container">  
</div>

Khi cần chỉnh sửa thông tin shop của người bán, có thể cập nhật thông tin shop và các thông tin khác bằng cách sử dụng phương thức update.

Sử dụng cho framework react:

Cập nhật các tham số của WidgetConfigProvider để cập nhật cấu hình widget

Sử dụng JS thuần:

JSONWord Wrap

  
import { update } from '@tiktokshop/widget-kit';//Reference method depends on the selected integration scheme  
  
update({  
  config: {  
      shopId: 'xxx', //seller id, such as 123456  
      oecRegion: 'xxx',//country,such as US  
      appKey: 'xxx',//The key corresponding to the merchant's creation service  
      isvInfo: {  
        name: 'xxx',//ISV name,such as OPEN_PLATFORM  
      },  
    },  
  getToken: getWidgetToken,//get auth token  
});

Reference API

Input Parameters

Properties	Type	Require	Sample	Properties description
config	Object	Y		cấu hình cơ bản của widget
shopId	string	Y	'123456'	seller id, dùng để theo dõi sự kiện (event tracking)
oecRegion	string	Y	'US'	khu vực của người bán, điền mã chuẩn của quốc gia nơi người bán đặt trụ sở, chẳng hạn 'US', 'GB', v.v.
appKey	string	Y	'xxxxx'	được cấp bởi service market, dùng để xác thực
isvInfo	Object	Y		thông tin liên quan đến ISV
name	string	Y	'xxxxx'	tên của ISV
getToken	Promise	Y		phương thức promise để lấy token
token	string	Y	'eyJhbGciOiJIUzUxMxxxxxxxx'	token
expire_at	string	Y	'1703227531'	thời điểm hết hạn
remotes	[]Object	Y
name	string	Y	'@tiktokshop-widget/product:optimizer'	tên widget được tích hợp, do nền tảng mở (open platform) cung cấp

Tham số đầu ra của loadWidget trong @tiktokshop/widget-kit-react và @tiktokshop/widget-kit là khác nhau. Sự khác biệt cụ thể như sau:

@tiktokshop/widget-kit-react

Input Parameters

Properties	Type	Require	Sample	Properties description
name	string	Y	'@tiktokshop-widget/product:optimizer'	tên widget được tích hợp, do nền tảng mở (open platform) cung cấp

Output Parameters

Properties	Type	Sample
Component
(tên tùy chỉnh)	React.ComponentType	`JSON <br> const Component = loadWidget(name); <br> return ( <br> <div> <br> <Component /> <br> </div> <br> ); <br>`

@tiktokshop/widget-kit

Input Parameters

Properties	Type	Require	Sample	Properties description
name	string	Y	'@tiktokshop-widget/product:optimizer'	tên widget được tích hợp, do nền tảng mở (open platform) cung cấp

Output Parameters

Properties	Type	Sample
component
(tên tùy chỉnh)	Promise	`JSON <br> loadWidget(name).then((component: WidgetComponent) => { <br> view = component.create( <br> document.getElementById('widget-preview-container'), <br> ); <br> view?.render({}); <br> }); <br> <br> return ( <br> <div <br> className="widget-preview-container" <br> id="widget-preview-container"></div> <br> ); <br>`
create	(el: HTMLElement) => WidgetView
render	(props: Record<string, any>) => Promise
unmount()	Promise
update	(props: Record<string, any>) => Promise

Properties	Type	Require	Sample	Properties description
name	string	Y	'@tiktokshop-widget/product:optimizer'	tên widget được tích hợp, do nền tảng mở (open platform) cung cấp

Properties	Type	Require	Sample	Properties description
config	Object	N		cấu hình cơ bản của widget
shopId	string	Y	'123456'	seller id, dùng để theo dõi sự kiện (event tracking)
oecRegion	string	Y	'US'	khu vực của người bán, dùng để điều phối lưu lượng (traffic scheduling)
appKey	string	Y	'xxxxx'	được cấp bởi service market, dùng để xác thực
isvInfo	Object	Y		thông tin liên quan đến ISV
name	string	Y	'OPEN_PLATFORM'	tên của ISV
getToken	Promise	N		phương thức promise để lấy token
token	string	Y	'eyJhbGciOiJIUzUxMxxxxxxxx'	token
expire_at	string	Y	'1703227531'	thời điểm hết hạn

WidgetConfigProvider chỉ tồn tại trong @tiktokshop/widget-kit-react

Properties	Type	Require	Sample	Properties description
config	Object	Y		cấu hình cơ bản của widget
shopId	string	Y	'123456'	seller id, dùng để theo dõi sự kiện (event tracking)
oecRegion	string	Y	'US'	khu vực của người bán, điền mã chuẩn của quốc gia nơi người bán đặt trụ sở, chẳng hạn 'US', 'GB', 'ID', v.v.
appKey	string	Y	'xxxxx'	được cấp bởi service market, dùng để xác thực
isvInfo	Object	Y		thông tin liên quan đến ISV
name	string	Y	'xxxxx'	tên của ISV
getToken	Promise	Y		phương thức promise để lấy token
token	string	Y	'eyJhbGciOiJIUzUxMxxxxxxxx'	token
expire_at	string	Y	'1703227531'	thời điểm hết hạn
remotes	[]Object	Y
name	string	Y	'@tiktokshop-widget/product:optimizer'	tên widget được tích hợp, do nền tảng mở (open platform) cung cấp
preloadWidgetNames	string[]	N	['@tiktokshop-widget/product:optimizer']	tên widget được tích hợp, do nền tảng mở (open platform) cung cấp

RemoteWidget chỉ tồn tại trong @tiktokshop/widget-kit-react

Properties	Type	Require	Sample	Properties description
name	string	Y	'@tiktokshop-widget/product:optimizer'	tên widget được tích hợp, do nền tảng mở (open platform) cung cấp
className	string	N	''	classname của dom node
style	CSSProperties	N	`JSON <br> { <br> "width":100 <br> } <br>`	style của dom node
options	Record<string,any>	N		Cấu hình của component widget được truyền vào

JSONWord Wrap

export interface WidgetComponent {  
  create: (el: HTMLElement) => WidgetView;  
}

JSONWord Wrap

export interface WidgetView {  
  render: (props: Record<string, any>) => Promise<void>;  
  unmount(): Promise<void>;  
  update: (props: Record<string, any>) => Promise<void>;  
}

Danh sách thông báo lỗi

Error message	description
Please call init first	Bạn cần khởi tạo init trước khi sử dụng
Current name configuration not found	Tải tài nguyên không chính xác, vui lòng kiểm tra xem tài nguyên có bất thường hay không

FAQ

Nếu gặp sự cố trong khi sử dụng SDK, bạn có thể tham khảo tài liệu này để giải quyết.

Trang widget tải thất bại và interface để lấy token liên tục khởi tạo yêu cầu lặp lại.

giải pháp: Kiểm tra giá trị trả về và tham số của interface /api/v1/seller/widget/get, thường là do token không được truyền vào. Kiểm tra giá trị trả về của getToken trong mã và đảm bảo rằng dữ liệu sau được trả về.

SQLWord Wrap

if (res?.code === 0) {  
      return res?.data;//The token interfaces of different access parties return different data structures, and the ways of obtaining data are different here.  
    }

Danh sách lỗi của interface /api/v1/seller/widget/get

error code	error message	reason
36017010	Widget domain not match	Tên miền được cấu hình trong whitelist không khớp với tên miền thực tế.
36017005	Widget Token Is Expired	Widget token đã hết hạn
36017006	Widget token is invalid	Widget token được gửi không chính xác
36017008	app_key is not match	app_key is not match
36017009	Widget Token Shop Not Match	shopid bạn nhập vào không khớp với thông tin shop trong widget.
36004003	invalid client_key	Whitelist của appkey chưa được cấu hình. Bạn cần cung cấp tên miền và appKey cho nền tảng mở (open platform) và cấu hình whitelist.
I01008	Traffic is invalid	Khu vực của shop không khớp với phòng máy chủ (server room). Trong hầu hết các trường hợp, nguyên nhân là do shop_id và region không khớp nhau.

Lỗi được báo như sau

Giải pháp: Tên widget bị sai, vui lòng tham khảo tài liệu tích hợp để kiểm tra lại.

Hướng dẫn sử dụng Widget SDK

Hướng dẫn cập nhật Widget SDK

@tiktokshop/widget-kit

<Version 1.0.2>

<Version 1.0.0>

Added

@tiktokshop/widget-kit-react

<Version 1.0.2>

Added

<Version 1.0.0>

Added

Bắt đầu nhanh

Cấu hình môi trường phát triển

Thích ứng framework

Cài đặt các dependency

Tích hợp SDK

Điều kiện tiên quyết

Khởi tạo widget

Tải trước widget (Preload)

Tải widget

Cập nhật cấu hình widget

Reference API

Input Parameters

@tiktokshop/widget-kit-react

Input Parameters

Output Parameters

@tiktokshop/widget-kit

Input Parameters

Output Parameters

Danh sách thông báo lỗi

FAQ

Hướng dẫn cập nhật Widget SDK

@tiktokshop/widget-kit​

<Version 1.0.2>​

<Version 1.0.0>​

Added​

@tiktokshop/widget-kit-react​

<Version 1.0.2>​

Added​

<Version 1.0.0>​

Added​

Bắt đầu nhanh

Cấu hình môi trường phát triển​

Thích ứng framework​

Cài đặt các dependency​

Tích hợp SDK​

Điều kiện tiên quyết​

Khởi tạo widget​

Tải trước widget (Preload)​

Tải widget​

Cập nhật cấu hình widget​

Reference API

Input Parameters​

@tiktokshop/widget-kit-react​

Input Parameters​

Output Parameters​

@tiktokshop/widget-kit​

Input Parameters​

Output Parameters​

Danh sách thông báo lỗi

FAQ

@tiktokshop/widget-kit

<Version 1.0.2>

<Version 1.0.0>

Added

@tiktokshop/widget-kit-react

<Version 1.0.2>

Added

<Version 1.0.0>

Added

Cấu hình môi trường phát triển

Thích ứng framework

Cài đặt các dependency

Tích hợp SDK

Điều kiện tiên quyết

Khởi tạo widget

Tải trước widget (Preload)

Tải widget

Cập nhật cấu hình widget

Input Parameters

@tiktokshop/widget-kit-react

Input Parameters

Output Parameters

@tiktokshop/widget-kit

Input Parameters

Output Parameters