OmniSegment

埋碼

Table of Contents

• TS 新版埋碼
  • 環境設定
  • 設定 scripty
• 埋碼檢查
  • 註冊會員的埋碼
• GTM (提交新版本後請客戶上線)
• 各系統商
  • 尚峪 Shang Yu
  • 91APP
  • CYBERBIZ
  • SHOPLINE
  • Shopify
  • QDM
• debug
• INI 舊版埋碼
• 客戶自行埋碼環境
• 推薦商品版位網頁內嵌開發
• 測試 webpopup
• Troubleshooting
  • i13n
  • Port 7000 被佔用 ?
  • Local API CORS issue

TS 新版埋碼

環境設定

1. 依據商家的設定 TID in fetchScriptConfig.ts

   const devScriptId = "OA-7b7520dd";
   

2. 依據商家的 TID 新增 ts file src/user2/

     {
       tid: string;
       defaultHost?: DefaultHostEnum;
       modules: {
         webPopup?: boolean;
         aiRecommender?: {
           enabled?: boolean;
           platformType?: AiRecommenderPlatformType;
         };
       };
       actions: (() => Promise<void>)[];
     }
   

3. 啟用 corepack
   如有使用其他方式安裝yarn如brew (which yarn看到的路徑會像這樣 /opt/homebrew/bin/yarn) 請移除後改用此方式安裝

     corepack enable
   

4. 啟動 dev-serve

     yarn dev
   

   entries

   http://localhost:7001/[entry]
   
     omnitag.js
     tag-app.js
     tag.js
     tagDev.js
     tag-poc-jp.js
     tag-jp.js
     omni-webpush.js
   

5. 打包部署

     yarn build
   

6. 單元測試

   • 手動:

       yarn test
     

   • 監控模式: 測試檔案或者測試檔案中引用的模組有更動會自動重跑

       yarn test:watch
     

scripty 設定

• scripty

• Create/Edit Script 中

  • Name 可以隨意填，自己好記好區別即可

  • Javascript Code 部分按照環境填入以下代碼

    • ts 版本環境

      (function () {
        var doc = document;
        var el = doc.createElement("script");
        el.src = "http://localhost:7001/omnitag.js";
        var s = doc.getElementsByTagName("script")[0];
        s.parentNode.insertBefore(el, s);
      })();
      

    • ini 版本環境

      (function () {
        var doc = document;
        var el = doc.createElement("script");
        el.src = "http://localhost:7001/tagDev.js";
        var s = doc.getElementsByTagName("script")[0];
        s.parentNode.insertBefore(el, s);
      })();
      

    • 客戶埋碼版本環境

      (function () {
        var doc = document;
        var el = doc.createElement("script");
        el.type = "text/javascript";
        el.async = true;
        el.src = "http://localhost:7001/tag-app.js";
        var s = doc.getElementsByTagName("script")[0];
        s.parentNode.insertBefore(el, s);
      })();
      

  • Run script if [URL] [Contains] Following input 這邊填入商家的網址
  • Trigger 選擇 Automatically [On Page Load] 後按下 Create/Update Script
  • 開啟商家的網址，打開 console 就可以開始開發

埋碼檢查

• 支援商品屬性

• 在店家網址完成註冊後進入 omnisegment 顧客頁面點擊會員

  • 
  • 
• 查看購買紀錄
  • 
• 或查看瀏覽紀錄
  • 

註冊會員的埋碼

• 不使用個人資料也可以驗證註冊這一段的埋碼，透過使用線上收簡訊驗證碼小工具
  • sms.sellaite
  • Receive SMS
• 測試信箱小工具 - temp-mail

埋碼 check list

- 要檢查的 **事件** ? - 所有的事件除了 web 需要檢查之外也含蓋 **mobile** - 每一個頁面 - `init` - `impression` - 這邊會需要注意的是，要有 product 的 id  - `Search` - 首頁 - `AddToCart` - `clickProduct` - 購物車 - `RemoveFromCart` - `ClickCartIcon` - `ClickCheckout` - `ClickConfirmCheckout` - `Purchase` - 單一商品頁面 - `ViewContent` - `AddToCart` - 相關商品清單 - `clickProduct` - `AddToCart` - 商品清單頁面 - `AddToCart` - `clickProduct` - 這邊需要特別注意的情境 - 新開 new tab 到 單一商品頁面 - 在原本的頁面跳轉 到 單一商品頁面 (這邊可以搭配 omnisegment 顧客頁面的瀏覽紀錄 debug) - 註冊會員 - `CompleteRegistration`

GTM (提交新版本後請客戶上線)

請參考 wiki

埋碼環境

- 新版 ts 埋碼 `omnitag.js` ```html ``` - 舊版 ini 埋碼 `tag.js` ```html ``` - 客戶自行埋碼 `tag-app.js` ```html ```

各系統商

尚峪 SHANG YU

• 尚峪有提供 Datalayer，事件及資料都從 Datalayer 取得。
• 埋碼時若發現「事件」未觸發，需請 CS 跟尚峪調整 Datalayer。

91APP

• 測試站
• 91APP 有跟我們合作，如果只需要單純埋碼，不需要其他功能（WebPopup / AI 商品版位），則不需做任何處理。如果需要其他功能，則需要在 GTM 上新增 Tag。

• uid 採用 GTM 自定義變數方式帶入，而 GTM 變數則可在該 GTM 中搜尋，可參考以下方式：

  1. 進入指定 GTM 容器，點選「變數」

  

  1. 滑到下方的「使用者定義的變數」，並搜尋「MID」，目前有使用過的名稱是Omnisegment_MID / cookie_MID

  

  1. 找到名稱後點擊該變數，確認 Cookie 名稱是 MID 即可使用該變數名稱

  

  // enable WebPopup
  <script>
    window.i13nData = {
      tagId: "[Your-TID]",
      uid: , // e.g. 
      disableHandleImpression: true,
    };
  </script>
  <script async src="https://omnitag.omniscientai.com/tag-app.js"></script>
  

  // enable WebPopup and AI Embedded
  <script>
    window.i13nData = {
      tagId: "[Your-TID]",
      uid: ,  // e.g. 
      disableHandleImpression: true,
      aiRecommender: {
        enabled: true,
        platformType: "91app"
      }
    };
  </script>
  <script async src="https://omnitag.omniscientai.com/tag-app.js"></script>
  

• 在 WebPopup 觸發條件中，目前 Refund / Search 事件無法觸發，其他事件均可。
• 如果該環境下抓不到 cookie MID，uid 相關的條件及模組也無法適用，像是 WebPopup 設定中的「會員登入」/「Line 狀態」及特定 WebPopup 類別 Line 綁定模組。

CYBERBIZ

• 測試站

SHOPLINE

• 測試站 1
• 測試站 2

SHOPIFY

• 測試站
• JP 測試站
• 測試購買的信用卡資料，可參考 Shopify 官方文件
  • 卡片持卡人名稱 Bogus Gateway
  • 信用卡號碼： 1 交易成功、2 交易失敗、3 支付商錯誤
  • CVV 任意三位數 e.g. 111
  • Expiry Date：任何有效的未來日期 e.g. 12/34

QDM

• 測試站

Debug

正式環境下的 debug 方式

❗️ 下方的方法一跟方法二只能擇一 1. 方法一：使用本地端打包後的正式環境版 ini 檔 (u/OA-OOXX.ini) - 在瀏覽器開發者工具中的設定啟用 本地覆寫 -  - 開啟瀏覽器開發者工具的 `網路` 頁籤尋找正式環境的埋碼腳本請求然後在來源面板中開啟 -  - 開啟瀏覽器開發者工具找到 `原始碼` -> `檔案` - 尋找正式環境的埋碼腳本 e.g `https://omnitag.omniscientai.com` -> `tag.js?id=OA-OOXX`. - 點選 `儲存以覆寫` - - 接著在 `覆寫` 頁籤下可以找到剛剛的檔案 - - 在終端機環境下在 `compile.sh` 所在資料夾下執行 `./compile.sh rd` - 打包完的檔案會在 `/omnitag/assets/tagDebug.bundle.js` - 支援指定 ini 檔 `./compile.sh rd 3d6f1ff4` - 把檔案內容複製貼上到 `覆寫` 頁籤下的檔案後存檔即可，也可在 vscode 中處理 - 打包完的檔案會在 `/omnitag/assets/tagDebug.bundle.js` - ❗️ 更改 ini 不需要再重新覆寫，reload 即可同步更新 - vscode 示意圖:  2. 方法二：使用本地端打包後的開發環境版 ini 檔 (src/user/OA-OOXX.ini) - 在 local 啟動專案後在 客戶的網頁上 block Request URL: `https://omnitag.omniscientai.com/tag.js?id=OA-xxxxx` - 透過 Chrome extension - [HTTP Request Blocker](https://chrome.google.com/webstore/detail/http-request-blocker/eckpjmeijpoipmldfbckahppeonkoeko/related?hl=en) block `*://omnitag.omniscientai.com/*` / `*://usergram.omniscientai.com/*.`  - 透過擴充功能彈性的在我們想要的網站開啟阻擋清單  - 手動 block request 

INI 舊版埋碼

開發前的環境建置

#### 設定 `ini file` - 依據商家的 TID 新增 ini file in `src/user/` - tagId 按照商家的 TID 設置 ```ini tagId=OA-XXXXXXXX #商家的 TID ``` - `tag_gtag_id`, `tag_gtag_gaId` 不用改 ```ini tag_gtag_id="GTM-TW79K5B" tag_gtag_gaId="G-C2HNKLYPCW" ``` #### 設定 `tag_dev.js` - 在 tag_dev.js 中的 iniUrl，init 的檔名對應上面的 `tagId`。 ‼️ 這邊 iniUrl 的 port 須對應到 `scripty` 上使用的 port，以及 package.json 上 `yarn start` 的 port ``` const iniUrl = "http://localhost:7000/src/user/OA-1597cbff-2.ini"; ``` - `defaultMpHost` 為收集埋碼事件的 server， 這裡的 `tagId` 為 omnisegment 中帳號所屬的組織 id， 在 omnisegment 中某個帳號只能看到該組織底下的事件收集資料， 可在 `http://localhost/ma/setting/?type=TRACKING` 中查看帳號所屬的組織 id ． ```js { path: ["defaultMpHost"], value: "http://localhost:8000", // localhost 必須用 http }, { path: ["tagId"], value: "OA-c19eb6", // 以local為例，預設是測試管理者帳號admin@RUB的TID }, ``` 

客戶自行埋碼環境

開發前的環境建置

#### 設定 app.js - 直接在下方指定參數 ```js { path: ["defaultMpHost"], value: takeSettingWithEnv({ development: DefaultHostEnum.DEV, production: DefaultHostEnum.TW, }), }, { path: ["tagId"], value: takeSettingWithEnv({ development: "OA-c19eb6", production: i13nData.tagId, }), }, { path: ["aiRecommender"], value: takeSettingWithEnv({ development: { enabled: true, platformType: AiRecommenderPlatformTypeEnum["91App"], }, production: i13nData.aiRecommender, }), }, ```

推薦商品版位網頁內嵌開發

開發環境設置

### OS 環境設置 - 開啟 `Module Permission`: `ProductEmbed` - 打開後登入 OS http://localhost/ma/setting/?&type=WEBPOPUP_EMBED 並打開設定 - 記得也要開啟帳號進階權限下的 `可控管渠道發送` http://localhost/ma/setting/?&type=PERMISSION - 完成後即可在 http://localhost/ma/edm/webpopup_embed 下編輯模板 - 目前有三個預設常態性模板分別代表 (首頁、商品頁、結帳頁)，編入編輯並啟用即可讓推薦商品內嵌模板 API 正常取得資料 (http://localhost/ma_cms/get-all-routers/?species=product_embed) - 同一時間透過 API 取得的模板最多兩個，預設跟限定期間模板 - abtest 只在限定期間模板下可以設定 - 推薦商品內嵌設定關閉或沒有權限下 API 會報 403 - 根據是否取得模板資料、推薦商品內嵌設定開關與權限決定顯示與否 （限定模板 -> 預設模板 -> 不顯示） - 後端會回傳時間範圍內的模板，前端不額外判斷時間範圍 ### omnitag 功能開關 - 客戶自行埋碼環境: app.js ```js client(i13nData, (configs, cb) => cb(configs, [ ...getOverWrite(), { path: ["defaultMpHost"], value: takeSettingWithEnv({ development: DefaultHostEnum.DEV, production: DefaultHostEnum.TW, }), }, { path: ["tagId"], value: takeSettingWithEnv({ development: "OA-c19eb6", production: i13nData.tagId, }), }, { path: ["aiRecommender"], value: takeSettingWithEnv({ development: { enabled: true, platformType: AiRecommenderPlatformTypeEnum["91App"], }, production: i13nData.aiRecommender, }), }, ]) ); ``` - ini 檔埋碼環境: OA-123.js ```ini ; User: bebittech shopline test https://bebittech.shopline.test.com/ ; type: Shopline ; Tags currencyCode=TWD tagId=OA-123 ... aiRecommender_enabled=true aiRecommender_platformType=shopline ... ``` - ts 檔埋碼環境: OA-123.ts ```js function getClientConfig(): ClientConfig { return { tid: "OA-123", modules: { webPopup: true, aiRecommender: { enabled: true, platformType: AiRecommenderPlatformTypeEnum.Shopline, }, }, actions: [ setUid, productImpression, ... ], }; } ``` ### 使用假資料 - 客戶自行埋碼環境: tagBase.js - ini 檔埋碼環境: tag_dev.js - ts 檔埋碼環境: omnitag.js ``` if (aiRecommender?.enabled) { aiRecommenderPlugin.init({ hostDomain: defaultMpHost, config: { platformType: aiRecommender?.platformType, tagId, clientId: getClientId(), userId: uid, demo: true, }, }); } ``` ### 參考資料: [推薦商品版位網頁內嵌](https://github.com/beBit-tech/omnitag/wiki/%E6%8E%A8%E8%96%A6%E5%95%86%E5%93%81%E7%89%88%E4%BD%8D%E7%B6%B2%E9%A0%81%E5%85%A7%E5%B5%8C)

測試 webpopup

開發測試注意事項

1. tid 要設定得跟 OS 開發環境上的一樣  2. 檢查測試網站的 session storage  - 當有舊的 cache 存在時，進入 storage 點擊 clear site data 

Inspect popup

在 console 輸入 inspectPopup(popup id) 可調出 popup 觸發條件判定結果列表，並進入 debugger 模式，可存取諸如 context, uid、cid 等。

Webview history helper

在 console 輸入 omnitagPageviewHistoryHelper 及可使用提供的 helper function

• push(url, title) 新增 data
• update(id, key, value) 更新 table
• remove(id) 移除 table
• getAll() 取得所有資料
• getByPastDays(days) 取得過去 n 天資料
• print(table or db object) 顯示資料
• help() 取得相關使用說明

Troubleshooting

i13n

• 許多 method 是寫來避免不支援 ES6 的狀況。 例如 merge, arrayFrom
• About US
• How to add OmniTag with GTM

• 使用 i13n.dispatch 的型別提示，可參考下面範例。其他尚未有型別定義的請使用 any

  import { type Dispatch } from "../types";
  const { dispatch, getUserId }: { dispatch: Dispatch; getUserId: any } = window.i13n;
  

  或者如果你要接自定義事件的型別，可以這樣寫

  import { type Dispatch } from "./types";
  // 通常下面的 category 要是 `"Ecommerce"`, value 要 string type 
  type CustomEvent =
    | { I13N: { action: "ClickChatbot"; category: "Ecommerce"; value: string } }
    | { I13N: { action: "Clickreward"; category: "Ecommerce"; value: string } };
  
  const dispatch: Dispatch<CustomEvent> = window.i13n.dispatch;
  

Port 7000 被佔用 ?

• 如果用 MacOS 的話很可能預設 AirPlay 開啟並佔用 port 7000，可以去關掉 AirPlay

  [Why is Control Center on Monterey …

  Apple Developer Forums](https://developer.apple.com/forums/thread/682332)

Local API CORS issue

SHOPLINE 平台本身有使用 Sentry，開發時有時會因為 Sentry 導致 local API 有 CORS issue。這時可以在 HTTP Request Blocker 上可加入 *://*.sentry-cdn.com/*：

如何手動發送 impressions through pageView (SPA)

i13n pageView 預設為自動發送，如果 impressions 為非同步取得則可能發生 race condition。目前新客戶在 detail impression 串接上已建議採用較彈性的 ViewContent，但 list impressions 如仍有需求場景，可於關閉自動發送 pageView 機制後自行手動發送：

async function getClientConfig(): Promise<ClientConfig> {
  return {
    tid: "{tid}",
    waitForUid,
    initCompleteActions: [sendPageViewAsync],
    disableHandleImpression: true, // 為 true 時不會自動發送 pageView
  };
}

function sendPageViewAsync() {
  // 取得資料後
  dispatch({ i13nPage: { impressions } }); // update store
  dispatch("manualPageView"); // send beacon
}