Catalog tracking

Giữ một catalog gồm event, property và rule cho mỗi app: sửa như một danh sách, import từ sheet taxonomy, xem flow nào đang kiểm gì.

Mỗi app có một file catalog trong workspace, ví dụ tracking-specs/mydmv.yaml. File chứa các rule mà mọi run được kiểm theo: event nào tồn tại, property và giá trị cho phép của chúng, cùng các rule chung. Những gì một flow mong đợi thì không nằm ở đây: chúng nằm trong flow, ở các step assertEvents. Xem Tracking.

Để tạo catalog mới, chọn File → New File… (⇧⌘N), chọn Tracking Catalog rồi đặt tên theo app. Scout tạo tracking-specs/<tên>.yaml chưa có event nào và mở nó dưới dạng catalog: bấm Import… để điền từ sheet taxonomy, hoặc + → Event dưới danh sách để nhập từng event bằng tay.

Mở một file trong tracking-specs/ và dùng nút chuyển trên thanh nhảy:

Chế độ	Dùng để
Catalog	Sửa event, user property, enum và rule mà không cần viết YAML
YAML	Sửa trực tiếp văn bản, hoặc những thứ chế độ catalog chưa hỗ trợ

Scout nhớ lựa chọn cho từng file. YAML vẫn là nguồn gốc: chế độ catalog chỉ đổi những dòng bạn đụng tới, nên comment và dòng trống được giữ nguyên.

YAML error

Chế độ catalog hiện một banner với error và số dòng. Bấm Mở YAML ở dòng N, sửa xong rồi quay lại.

Chế độ catalog

Danh sách ở bên trái, chi tiết của mục đang chọn ở bên phải. Thanh dưới cùng tóm tắt file, ví dụ "spec valid · 34 events · 21 enums · used in 3 flows".

Lọc. Ô Lọc ở thanh dưới danh sách lọc theo event, property, enum hoặc giá trị.
Nhóm. Events, User property, Enum và Rule chung.
Thêm và gỡ. Menu + thêm một Event, User property hoặc Enum, hoặc một rule chung từ mẫu. − gỡ mục đang chọn sau khi xác nhận. Enum mà property còn dùng thì không gỡ được; thông báo nêu tên các property đó.
Gỡ event mà flow đang kiểm. Scout hiện warning "Event này đang được kiểm ở N chỗ trong flow", và vẫn gỡ nếu bạn xác nhận.

Events

Một event là một form, từ trên xuống:

Phần	Ý nghĩa
Dòng tiêu đề	Tên event, đổi tên ngay tại chỗ. Scout đổi tên event ở mọi nơi nó xuất hiện trong catalog (rule, cross check, event đăng nhập) và hỏi trước, kèm số chỗ. Scout không đổi tên event bên trong các file flow. "Chưa thấy trong run nào" hiện cạnh tên khi có run mà chưa từng thấy event
Mô tả	Thêm mô tả… hiện khi chưa có mô tả
Property	Giá trị lấy từ run ở đầu section chọn run để so event với; giá trị và gợi ý lấy từ run đó. Sau đó là một hàng cho mỗi property: tên, "kiểu · Bắt buộc" hoặc "kiểu · Không bắt buộc", và bên phải là giá trị cho phép viết thành lời ("Bất kỳ" khi không kiểm gì, pattern bằng chữ monospace, "≥ N" cho số). Biểu tượng trạng thái đánh dấu property mà run gần nhất làm sai. Mũi tên (Sửa) mở property. Thêm property… nằm dưới danh sách. Chú thích ghi property vi phạm rule sẽ làm run fail
Property không có trong danh sách	Run xử lý thế nào khi app gửi property mà event không liệt kê: Theo rule chung (Warning), Bỏ qua, Warning hoặc Error
Được kiểm trong flow và Bị cấm trong header của flow	Nơi các flow kiểm hoặc cấm event này, xem bên dưới. Ẩn khi trống
Rule liên quan	Các rule chung nêu tên event này, viết thành câu. Bấm một câu để sửa

Bấm mũi tên của một property để sửa trong popover: tên, Kiểu, Bắt buộc, giá trị cho phép và Xoá property. Property dùng chung cho nhiều event (một YAML anchor) có biểu tượng liên kết; khi sửa, Scout hỏi Sửa cả N event hoặc Chỉ sửa event này (tách bản riêng).

Giá trị cho phép

Trong popover của một property, trình sửa giá trị cho phép chọn cách kiểm giá trị:

Chế độ	Kiểm rằng giá trị
Enum dùng chung	nằm trong một danh sách có tên ở mục Enum. Chọn danh sách từ menu; sửa các giá trị sẽ đổi mọi property đang dùng nó ("Dùng ở N property")
Danh sách riêng	nằm trong một danh sách chỉ property này có. Enum mới từ danh sách này biến nó thành enum dùng chung
Regex	khớp một pattern. Pattern sai sẽ bị đánh dấu
Số ≥	là số, ít nhất bằng giá trị này
Bất kỳ	giá trị nào cũng pass

Tách thành danh sách riêng sao chép các giá trị của enum dùng chung vào property này, để bạn sửa mà không đụng tới các property khác.

Gợi ý từ một run

Khi đã ghi được một run, event còn liệt kê những gì run đó cho thấy:

Gợi ý	Hành động
Giá trị mới của property có enum	Thêm vào giá trị cho phép, hoặc Là bug của app để bỏ qua
Property mà event không liệt kê	Thêm, hoặc sửa app
Thiếu property bắt buộc	Sửa app, hoặc đổi property thành không bắt buộc

User property và enum

User property và Enum dùng cùng kiểu form như event. User property có Kiểu, Giá trị cho phép (cùng trình sửa như event), Khi sai (Mặc định (theo rule chung), Bỏ qua, Warning, Error) và Cần team xác nhận.
Enum liệt kê các giá trị: thêm, đổi hoặc gỡ một giá trị, hoặc dán nhiều dòng để thêm nhiều giá trị. Cần team xác nhận giữ danh sách giá trị mà team chưa thống nhất ở mức warning. Used in hiện các property dùng enum. Danh sách khác nhau theo nền tảng hiện "Theo nền tảng: sửa trong YAML", kèm Mở YAML.

Được kiểm trong flow

Mỗi event có flow kiểm hiện Được kiểm trong flow kèm số chỗ: mỗi file:line mà assertEvents của một flow nêu tên nó, kèm các giá trị viết ở đó. Bấm một hàng để mở flow ở dòng đó. Bị cấm trong header của flow liệt kê các flow nêu event trong tracking.forbid. Cả hai mục ẩn khi trống.

Rule chung

Rule chung chứa những gì không gắn với một event. Mỗi rule được viết thành một câu kèm severity, ví dụ:

Giá trị paywall id, placement giống nhau ở Paywall Viewed và Paywall Skipped · fail
Nếu Purchase Completed có is trial = true thì Home Screen Viewed có access level = trial · warning · cần xác nhận
step number của Onboarding Step Viewed tăng dần từ 1, mỗi lần +1
Không được có Application Opened · fail
lesson_id là tên sai, đúng là lesson id

Các nhóm rule là Event chưa có trong catalog và event cấm, Tên property, Property và user property chưa có trong catalog, Kiểu dữ liệu, Kiểm tra chéo, User property theo event, Đăng nhập, profile Amplitude, Kiểm trên server và So iOS/Android. Bốn nhóm cuối được mô tả trong Tracking.

Thêm một rule

Bấm + dưới danh sách và chọn một mẫu trong Rule chung. Bạn không bao giờ phải gõ rule: mọi lựa chọn đều lấy từ catalog.

Mẫu	Ghi
Giá trị giống nhau giữa các event	Các property đã liệt kê phải có cùng giá trị ở mọi event đã liệt kê
Nếu … thì …	Nếu một event có giá trị property, thì event khác phải có giá trị property
Số tăng dần theo từng lần	Property số tăng một step ở mỗi event, từ giá trị bắt đầu
Event không được có	Event không bao giờ được phép xuất hiện
Event được phép ngoài catalog	Event không có trong catalog vẫn được chấp nhận, không warning
Tên property sai thường gặp	Nêu một cách viết sai và cách viết đúng

Popover có ô chọn event và property (menu Chọn một tên), Khi sai (Error hoặc Chỉ warning) và Cần team xác nhận. Lưu bị vô hiệu, kèm lý do, cho đến khi điền đủ mọi ô. Bấm câu của một rule có sẵn để sửa trong cùng popover, hoặc Gỡ nó.

Thử với run 14:02 chạy bản nháp trên run mới nhất trước khi bạn lưu và cho biết cái gì sẽ pass hay fail. Nút ẩn khi chưa có run.

Severity

Severity	Tác dụng
Error	Lần kiểm fail và run fail
Warning	Ghi vào report, run không fail
Bỏ qua	Không kiểm

Rule đánh dấu Cần team xác nhận chạy như warning cho đến khi có người bỏ dấu.

Event mà catalog chưa có

Event mà app gửi nhưng catalog không liệt kê sẽ theo Event chưa có trong catalog trong rule chung (mặc định là warning). Danh sách hiện chúng dưới App gửi nhưng catalog chưa có · N, kèm số lần và run nào. Bấm Thêm vào catalog để tạo event từ những gì app đã gửi.

Theo chiều ngược lại: bật Chưa flow nào kiểm, nút ◇ ở cuối ô Lọc. Danh sách chỉ còn các event không flow nào kiểm.

Lần kiểm trong flow nêu một event chưa có trong catalog cũng có cùng cách sửa ngay từ flow: xem Cách sửa nhanh.

Import taxonomy của bạn

Nếu team giữ kế hoạch event trong một bảng tính, hãy để Scout điền catalog từ đó thay vì gõ tay.

Tải sheet về dạng .xlsx, hoặc từng tab dạng .csv hoặc .tsv. (Cũng đọc được .xlsm và .txt. .xls cũ, .ods, .numbers và link Google Sheet không đọc được.)
Trong chế độ catalog, bấm Import… trên thanh nhảy.
Bấm Chọn File… và chọn file. Với csv hoặc tsv, bạn chọn được nhiều tab cùng lúc.
Chọn Tên event: Display (cột display, là mặc định) hoặc Ingested.
Xem danh sách, bỏ tick những gì không muốn, và bấm Ghi vào catalog.

Scout đọc gì

Scout nhận ra từng tab theo tiêu đề cột, không theo tên tab:

Tab	Cần các cột
Events	`Event Name (Display)` (hoặc `Ingested Name`) và `Event Properties`
Event properties	`Property Name`, `Data Type`, `Used By Events`
User properties	`Property Name`, `Data Type`, và `Set By Events` hoặc `Source`

Dòng tiêu đề nhóm bị bỏ qua. Thiếu tab hoặc cột Events sẽ được báo trong danh sách issue; sửa sheet và chọn lại file. Thiếu tab property chỉ có nghĩa là phần đó không được so sánh.

Sheet hiện gì

Mục	Chứa
Event và property mới	Có trong sheet, chưa có trong catalog
Event và property thay đổi	Có ở cả hai nhưng khác nhau: property mới, hoặc kiểu khác
Bị xoá khỏi sheet	Có trong catalog, không còn trong sheet
Đã bỏ qua	Event do backend gửi (kiểm bằng server check), event SDK tự gửi, và user property do Amplitude đặt. Chúng không có ô tick

Bấm một hàng để xem các dòng nó sẽ ghi dưới Xem trước. Hiện thêm N liệt kê phần còn lại của một mục dài.

Mục nào được tick sẵn

Mục	Tick sẵn	Vì sao
Mục mới hoặc thay đổi thông thường	Có	An toàn để nhận nguyên
Mục cần xác nhận	Không	Sheet chỉ đưa giá trị enum làm mẫu, một kiểu bị trống, một property có nhiều định nghĩa, hoặc một tên xuất hiện hai lần. Hãy tick khi team đã thống nhất. Giá trị lấy từ mẫu được lưu thành enum đánh dấu Cần team xác nhận
Event bị xoá mà không ai dùng	Có	Catalog theo sheet
Event bị xoá mà flow đang kiểm hoặc rule đang nêu tên	Không	Gỡ chúng sẽ làm hỏng flow hoặc rule. Hàng đó cho biết chúng được dùng ở đâu

Property mới được ghi là bắt buộc, trừ property mà sheet đánh dấu chỉ iOS hoặc chỉ Android. Import không bao giờ ghi đè những gì bạn thêm tay: regex, severity, required, not_empty, giá trị tối thiểu, enum đã xác nhận và comment đều được giữ. Giá trị cho phép mà sheet thêm vào enum có sẵn thì được thêm; không có giá trị nào bị xoá.

Ghi và thay đổi file

Server ghi catalog, nên ⌘Z không hoàn tác được. Nếu cần, sửa lại trong chế độ YAML.
Nếu file catalog đổi trong lúc sheet đang mở, Scout đọc lại và kiểm tra lại sheet. Các tick vẫn giữ ở những mục không đổi; mục nào nội dung đã đổi thì bị bỏ tick để bạn xem lại.

Rule của engine cần biết

Mỗi event một định nghĩa. Cùng một tên event hai lần dưới events: là YAML error, và catalog không mở cho đến khi bỏ một cái.
global_rules chặt. Key không hợp lệ dưới global_rules là parse error, nên rule viết sai chính tả không bao giờ bị bỏ qua âm thầm. Property có enum_ref trỏ tới enum không tồn tại cũng là error.
language_independent_values. Thêm language_independent_values: { severity: error } dưới global_rules để bắt giá trị bị dịch. Giá trị chuỗi của property có enum, nằm ngoài enum đó và có chữ ngoài ASCII (ví dụ 车 thay cho car), sẽ fail theo severity này. Điều này đúng cả với enum đã xác nhận.
Cross check có severity. same_value, increasing_sequence và implies nhận severity (error hoặc warn; mặc định là error, và needs_confirmation hạ xuống thành warning). Nhóm same_value có liệt kê Paywall Viewed sẽ bắt đầu lại ở mỗi Paywall Viewed.
Không có scenario. Catalog có scenarios, shared_cross_checks, flow_id hoặc global_rules.unexpected_events sẽ bị từ chối. Dùng assertEvents trong flow và global_rules.unknown_events.

yaml

spec_version: 2
global_rules:
  unknown_events:
    severity: warn
    allowed: ["[Amplitude] Application Installed", "$exposure"]
  language_independent_values:
    severity: error
cross_checks:
  - { rule: same_value, properties: [paywall id, placement], across: [Paywall Viewed, Paywall Skipped] }
  - { rule: increasing_sequence, event: Onboarding Step Viewed, property: step number, start: 1, step: 1 }
  - rule: implies
    needs_confirmation: true
    if:   { event: Purchase Completed, property: is trial, equals: true }
    then: { event: Home Screen Viewed, property: access level, equals: trial }

Một enum và một property dùng nó:

yaml

enums:
  license type:
    values: [car, cdl, motorcycle]
events:
  License Selected:
    properties:
      license type: { type: string, required: true, enum_ref: license type }

Từ terminal hoặc plugin

Agent và script dùng cùng các thao tác qua HTTP trên server Studio:

Route	Làm gì
`GET /api/tracking/spec?workspacePath=…&path=…`	Trả YAML, `hash` của nó và model mà chế độ catalog dùng
`POST /api/tracking/spec/edit`	Áp các op `set`, `insert`, `remove`, `move` hoặc `rename` lên một path. `baseHash` phải khớp file, nếu không trả `409`; op sai hoặc catalog kết quả không hợp lệ trả `422`
`POST /api/tracking/spec/suggest`	Trả gợi ý từ một run, không ghi file
`POST /api/tracking/spec/try`	Áp op trong bộ nhớ và trả các kết quả kiểm của một run bị đổi, không ghi file
`POST /api/tracking/spec/rename-event`	Đổi tên một event và mọi tham chiếu tới nó trong một lần sửa
`GET /api/tracking/spec/usages`	Trả nơi các flow kiểm từng event
`GET /api/tracking/coverage`	Trả các event không flow nào kiểm, và event app đã gửi mà catalog chưa có
`POST /api/tracking/import/preview`, `/import/apply`	Xem trước và ghi một lần import taxonomy

Các trường của request và response được liệt kê trong flows/mydmv/tracking-specs/README.md của repository.

Catalog tracking ​

Chế độ catalog ​

Events ​

Giá trị cho phép ​

Gợi ý từ một run ​

User property và enum ​

Được kiểm trong flow ​

Rule chung ​

Thêm một rule ​

Severity ​

Event mà catalog chưa có ​

Import taxonomy của bạn ​

Scout đọc gì ​

Sheet hiện gì ​

Mục nào được tick sẵn ​

Ghi và thay đổi file ​

Rule của engine cần biết ​

Từ terminal hoặc plugin ​