Cho App Client

Mục lục

Tích hợp Market SDK

Nhúng Market Menu vào App

I. Tích hợp Market SDK

Market SDK là một thư viện javascript được Marketplace phát triển giúp app client có thể tích hợp dễ dàng và nhanh chóng. Market SDK hỗ trợ các ứng dụng web là Client Rendering và Server Rendering. Đồng thời cung cấp giải pháp định danh và quản lý quyền truy cập của người dùng dựa trên mô hình uỷ quyền (delegation authorization) của OAuth2.0 và OpenID Connect Core.

1. Tải Market SDK

Nếu app client là Client Rendering hoặc Hybrid Rendering

Bạn có thể download Market SDK: teko-market-v1 tại đây hoặc sử dụng command line:

npm install teko-market-v1

Nếu app client là Server Rendering

Khai báo thẻ <script> sau trong html:

<script src="https://unpkg.com/teko-market-v1@1.4.1/dist/bundle/teko-market.min.js"></script>

2. Khởi tạo Market SDK.

Gọi hàm khởi tạo

TekoMarket.auth.init(configs)

App Client truyền thông tin yêu cầu dưới đây để khởi tạo Market SDK.

Tham số đầu vào

Tên trường	Kiểu dữ liệu	Giá trị mặc định	Bắt buộc?	Mô tả
`clientId`	String	-	Có	Do Marketplace cung cấp - dùng để định danh các ứng dụng của đối tác tích hợp với Marketplace.
`scopes`	Array of Strings	-	Có	Truyền giá trị: `['openid', 'profile']`. Chi tiết xem mô tả về `scope` trong `.getUserInfo()` tại đây.
`oauthDomain`	String	-	Có	Do Marketplace cung cấp - dùng để validate session của user còn hiệu lực hay không.
`redirectUri`	String	`protocol//hostname:port`	Không	Do App cung cấp cho Marketplace - để Marketplace gọi báo cho App sau khi đăng nhập tài khoản user thành công.
`postLogoutRedirectUri`	String	`protocol//hostname:port`	Không	Do App cung cấp cho Marketplace - để Marketplace gọi báo cho App sau khi đăng xuất tài khoản user thành công.
`monitorSession`	Boolean	`false`	Không	Gán bằng `true` nếu bạn muốn lắng nghe các thay đổi của user session.

Code mẫu

Với các ứng dụng Server Rendering (sử dụng các ngôn ngữ như PHP, Python, Pearl, Java…)

Copy paste đoạn code dưới đây và sửa thông tin config theo giá trị được Marketplace cung cấp riêng.

<script src="https://unpkg.com/teko-market-v1@1.4.1/dist/bundle/teko-market.min.js"><script/>
<script>
  var configs = {
    clientId: "<client-id>", //sử dụng <client-id> do Marketplace cung cấp.
    redirectUri: "<callback-login-uri>", //App cung cấp cho Marketplace.
    postLogoutRedirectUri: "callback-logout-uri", //App cung cấp cho Marketplace.
    oauthDomain: "<market-oauth-domain>",
    monitorSession: true,
    scopes: ["<a-list-of-scopes-of-app>"], //Marketplace cung cấp cho App. 
  }
  window.TekoMarket.auth.init(config);
</script>

Với các ứng dụng Client Rendering hoặc Hybrid Rendering (sử dụng Js, NodeJS …)

Copy paste đoạn code dưới đây và sửa thông tin config theo giá trị được Marketplace cung cấp riêng.

import TekoMarketSDK from 'teko-market-v1'

const { TekoMarket } = TekoMarketSDK

var configs = {
  clientId: "<client-id>", //sử dụng <client-id> do Marketplace cung cấp.
  redirectUri: "<callback-login-uri>", //App cung cấp cho Marketplace.
  postLogoutRedirectUri: "callback-logout-uri", //App cung cấp cho Marketplace.
  oauthDomain: "<market-oauth-domain>",
  monitorSession: true,
  scopes: ["<a-list-of-scopes-of-app>"], //Marketplace cung cấp cho App. 
}
TekoMarket.auth.init(configs).then(() => {
  // The initial phase is finish.
  // Now you can do your logic.
  // For example, if you are using React:
  const rootElement = document.getElementById('root')
  ReactDOM.render(<App />, rootElement)
});

3. Tích hợp tài khoản cùng với App Server

3.1 Đăng nhập tài khoản

Khi user chọn “Đăng nhập”, App Client gọi hàm TekoMarket.user.login() của Market SDK để redirect user tới trang đăng nhập chung.

import TekoMarket from 'teko-market-v1'

const App = props => { 
  if (TekoMarket.user.isLoggedIn())  
    return <HomePageView userInfo={TekoMarket.user.getUserInfo()} /> /* Xem Ghi chú (1)*/
  return <LoginView />
}  
  
const LoginView = props => ( 
  <p onClick={() => TekoMarket.user.login() /* Xem Ghi chú (2) */ }> </p>
)

Ghi chú

(1) Là bước 9R trong Luồng xử lý đăng nhập App và bước 4R trong Luồng xử lý user chuyển App
(2) Là bước 2 trong Luồng xử lý đăng nhập App

3.2 Đăng xuất tài khoản

Gọi hàm logout của Market SDK

Khi user chọn “Đăng xuất”, App Client gọi hàm TekoMarket.auth.user.logout() của Market SDK để redirect user tới trang đăng xuất chung.

Lắng nghe thay đổi user session

Đoạn code dưới đây cho mục đích single sign out. Lưu ý, bạn cần đảm bảo đã gán monitorSession=true khi khởi tạo Market SDK:

// Should only call after Teko.init has resolved
TekoMarket.auth.user.events.addUserSessionChanged(() => {
  // alert('User session changed. Force user to re-login.')
  TekoMarket.auth.user.unloadUser()
  TekoMarket.auth.user.login()
})

TekoMarket.auth.user.events.addSilentRenewError(err => {
  console.err('Silent renew error. Details:', err)
})

Market menu là một icon được cung cấp bởi Marketplace cho phép app client tích hợp nhanh vào trang ứng dụng giúp người dùng có thể xem danh sách các app, cũng như chuyển nhanh giữa các ứng dụng tích hợp với Marketplace.

App Client tuỳ chọn vị trí nhúng marketplace menu icon bằng cách định nghĩa thẻ <iframe> dưới đây trong html tại vị trí mong muốn:

<iframe
  id="app-switcher"
  title="app-switcher"
  name='{
    "parentOrigin": "<window.location.origin>"
    "align": "right | left" 
  }' // parentOrigin is required; align is optional with default value "left"
  src="<MARKET_WEB_DOMAIN>/app-switcher" //Marketplace cung cấp cho App
  frameborder="0"
  scrolling="no"
  height="52px"
/>

Ví dụ:

// Reactjs
<div
  style={{
    position: "relative",
    width: 52,
    height: 52,
    zIndex: 10,
  }}
>
  <iframe
    id="app-switcher"
    title="app-switcher"
    name={JSON.stringify({ parentOrigin: window.location.origin, align: "left" })}
    src="https://market.dev.teko.vn/app-switcher"
    frameBorder="0"
    scrolling="no"
    height="52px"
  />
</div>

<!-- HTML -->
<iframe
  id="app-switcher"
  title="app-switcher"
  name='{"parentOrigin": "https://market.dev.teko.vn","align":"right"}'
  src="https://market.dev.teko.vn/app-switcher"
  frameborder="0"
  scrolling="no"
  height="52px"
/>