使用 Amplitude Data 以及 Ampli Wrapper 來規劃、追蹤與驗證產品分析

Published in

iKala 技術部落格

9 min readNov 2, 2023

Retso 在 iKala KOL Radar 擔任 Senior Software Engineer
在本篇文章中，我將分享 KOL Radar 如何使用 Amplitude Data 以及 Ampli Wrapper 
來分析產品。

Background

何謂 Amplitude Data

制定追蹤計畫是產品分析的工作流程裡主要的環節之一，而 Amplitude Data 就是為此而生，它是幫助產品分析人員制定、管理以及觀察追蹤計畫的網頁工具，確保產品的追蹤計畫是即時更新的且最具成效的。
Amplitude Data 不只對產品分析人員有幫助，也對產品開發人員有很大的幫助，它提供一站式的追蹤計畫，讓開發人員清楚的了解到有什麼事件需要在什麼情境下被追蹤，且清楚的知道事件需要的資料有哪些。

何謂 Ampli Wrapper

Ampli Wrapper 是一套 CLI 工具，用來將 Amplitude Data 定義的追蹤計畫下載下來，並自動產生對應程式語言的 SDK，讓開發者可以快速且安全（type-safe）的傳送追蹤事件，支援各大主流平台的語言（TypeScript、Swift、Go … 等)

Why

為何選擇 Amplitude Data

規劃追蹤計畫的方式有很多種，舉凡 Google Doc、投影片、Google Sheet …等，最常見的應該就是透過 Google Sheet 了

除非特別針對 Google Sheet 做特殊處理，但通常會有幾個常見的問題：

事件參數定義困難

很難清楚的定義每個事件該傳哪些參數
很難定義每個參數該以什麼 Type 儲存

事件參數難以重復使用

相同的事件參數需要重複定義並重複撰寫說明

較難驗證事件

因為 Google Sheet 本身只是用來規劃追蹤計畫的工具，如果要驗證事件的話還是會需要回到事件追蹤平台本身，相關人員只能反覆的往返追蹤計畫與追蹤平台

為何選擇 Ampli Wrapper

以 TypeScript 專案為例，想要傳送 Amplitude 事件我們可以這麼做

amplitude.trackEvent("Product Viewed", props);

這樣做會有幾個可能問題

工作效率

工程師必須往返 Google Sheet 複製追蹤計畫上定義的事件資料

Typo

因為事件名稱是純文字，容易打錯字

事件參數（Event Properties）難以及時驗證資料正確性

因為每個事件皆個別手動維護的原因，難以即時的驗證每個事件參數符合追蹤計畫上的定義

How

如何使用 Amplitude Data 來規劃事件

💡 如何設定專案，請參考官方的 Quick Start

設定完成後，進入 Amplitude Data 會看到以下畫面

追蹤計畫選單：這邊可以選擇要編輯的追蹤計畫
分支選單：Amplitude Data 最新的都會在 main 分支，且 main 分支是不可編輯的，避免誤改
Events: 該追蹤計畫所有定義的事件都會顯示在這邊
Properties：定義使用者屬性以及事件屬性的地方

點擊 Events 進入事件列表，這邊我已經先建立好了 Clicks Register 事件，點擊事件名稱可以開啟事件編輯頁面

Sources: 定義該事件會透過哪些來源傳送
Properties: 定義該事件會需要傳送哪些事件參數，此參數為整個追蹤計畫共用，可以在 Properties 頁面看到所有的參數，方便重復使用

點擊 from 可以進到編輯事件參數頁面

Description: 事件參數描述，可以定義傳送時機等描述，讓工程人員更理解參數的用意
Required: 勾選後此事件會變成必填，除了工程人員可以即時的獲得錯誤提示外，Amplitude Data 也會顯示此事件參數是否符合追蹤計畫的定義
Type: 事件參數的屬性，可以定義此事件參數要以 String, Number …等屬性傳送

上述追蹤計畫定義完成後，將可使用 Ampli Wrapper 來自動產生 SDK 供工程師串接

使用 Ampli Wrapper 來傳送事件

💡 如何設定專案，請參考官方的 Quick Start

設定完成後，Ampli Wrapper 會自動產生 index.ts 檔案，裡面的內容就是我們在 Amplitude Data 定義的追蹤計畫，除了將以往以純文字傳送的事件名稱現在變成了 function 可以直接呼叫外，連較複雜的事件參數也可以直接在 function 裡面知道需要傳送的參數有哪些，如果傳錯的話也會當下顯示錯誤提示，減少往返追蹤計畫的時間與降低錯誤發生率

import * as amplitude from '@amplitude/analytics-browser';

export type Environment = 'production' | 'development';

export const ApiKey: Record<Environment, string> = {
  production: 'xxx',
  development: 'xxx'
};

export interface ClicksRegisterProperties {
  from: 'nav' | 'root';
}

export class Ampli {

 load(options: LoadOptions): PromiseResult<void> {
  // load SDK logic...
 }

  identify(
    userId: string | undefined,
    properties?: IdentifyProperties,
    options?: EventOptions,
  ): PromiseResult<Result> {
  // Identify a user logic...
 }

 clicksRegister(
    properties: ClicksRegisterProperties,
    options?: EventOptions,
  ) {
    return this.track(new ClicksRegister(properties), options);
  }

}

export const ampli = new Ampli();

如何使用 SDK

首先我們需要先初始化，只需要呼叫 ampli.load 就可以初始化 SDK 了，它會根據 environment 讀取對應的 apiKey

import { ampli } from '@/ampli'

ampli.load(environment: isDev ? 'development' : 'production')

接下來只需要在要傳送的地方呼叫事件 function，就會傳送事件囉

import { ampli } from '@/ampli'

<button onClick={() => ampli.clicksRegister({ from: 'nav' })>
 Register
</button>

如果想要把個人事件歸因回某個使用者身上也非常的簡單，只需要呼叫 identify 並給對應的 userId 就可以囉

import { ampli } from '@/ampli'

ampli.identify('123')

One more thing…

前面講述了如何使用 Amplitude Data 來規劃追蹤計畫，並透過 Ampli Wrapper 的程式碼生成功能來快速的建構 SDK，並使用 SDK 傳送追蹤事件，但 Ampli Wrapper 能做到的還不只這樣，這邊將介紹 KOL Radar 如何在有 Amplitude 事件被觸發的同時，使用 Ampli Wrapper 裡的 Plugin 自動將事件轉送至 Google Analytics

Ampli Wrapper 目前支援多種 Plugin，今天要使用的是其中的一種叫做 DestinationPlugin ，它會在事件被觸發的時候額外執行 execute 裡面的程式，所以我們可以這樣實作：

class SendGoogleAnalyticsEventPlugin implements DestinationPlugin {
  name = 'send-google-analytics-event'
  type = PluginType.DESTINATION as const

  setup(): Promise<undefined> {
    // Configure Google Analytics
    return Promise.resolve(undefined)
  }

  execute(context: Event): Promise<Result> {
    const isTrackEvent = !values(SpecialEventType)
      .map((type) => type.toString())
      .includes(context.event_type)

    if (isTrackEvent) {
      sendGoogleAnalyticsEvent(context)
    }

    return Promise.resolve({
      event: context,
      code: 200,
      message: '',
    })
  }
}

setup() 這邊可以放我們初始化 Google Analytics 所需要的邏輯
execute(context:) 這邊可以放要額外執行的邏輯

實作完上述 Plugin 後，要怎麼使用呢？方法也很簡單，只要在 SDK 成功初始化後加入就可以了：

import { ampli } from '@/ampli'

await ampli.load()
ampli.client.add(new SendGoogleAnalyticsEventPlugin())

註：上述內容部分為 untested pseudocode