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ì.

Catalog liệt kê các event mà app được phép gửi, ví dụ "Paywall Viewed", kèm property và các giá trị cho phép. Sau mỗi run, Astra Scout so các event app đã gửi với catalog rồi báo pass, warn hoặc fail. QA lead, analyst và dev quản lý catalog. Tester chỉ chạy flow thì không cần đọc.

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.

Các cách điền catalog

• Import… từ sheet taxonomy.
• + → Event mới… để nhập event bằng tay.
• + → Event Amplitude SDK… cho event mà Amplitude SDK tự gửi.
• Thêm vào catalog cho event app đã gửi.
• Catalog mẫu mà workspace mới có sẵn: tracking-specs/sample.yaml.
• Nhờ AI: skill edit-tracking-spec của plugin scout, xem Từ terminal hoặc plugin.

Chưa biết bắt đầu từ đâu? Xem Tracking: bắt đầu từ đâu.

Tạo catalog

1. Chọn File → File mới… (⇧⌘N). Sheet "Chọn mẫu cho file mới" mở ra.

   

2. Bấm ô Tracking Catalog, rồi Tiếp.

3. Gõ tên vào ô Tên. Dùng tên app, ví dụ mydmv. Dòng dưới ô cho biết thư mục: catalog luôn nằm trong tracking-specs/ của workspace, dù bạn đang chọn thư mục nào.

4. Bấm Tạo. Scout ghi tracking-specs/<tên>.yaml chưa có event nào và mở nó dưới dạng catalog.

5. Điền vào đó: Import… từ sheet taxonomy, hoặc nút + dưới danh sách.

Catalog hay YAML

Mở một file trong tracking-specs/. Thanh nhảy có một nút chuyển tên Mở dưới dạng với hai lựa chọn:

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ợ

Import… nằm cạnh nút chuyển; nút tắt khi YAML đang có error. 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

Từ vựng dùng trong chế độ này:

• Event: một sự kiện tracking, ví dụ "Paywall Viewed".
• Property: thông tin đi cùng một event, ví dụ paywall id.
• User property: thông tin gắn với người dùng, không gắn với một event.
• Enum: một danh sách giá trị cho phép có tên (ví dụ car, cdl, motorcycle) mà nhiều property dùng chung.
• Rule chung: rule không gắn với một event riêng.

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 ở thanh dưới danh sách lọc theo event, property, enum hoặc giá trị. Khi không có gì khớp, danh sách hiện màn "không có kết quả".
• Các mục. Danh sách có bốn mục: Events, User property, Enum và Rule chung.
• Nhóm. Khi event có Nhóm (lấy từ category của event trong sheet taxonomy, như Onboarding hay Paywall), mục Events chia event theo nhóm, theo thứ tự trong catalog, Không có nhóm ở cuối; hàng nhóm ghi như "Onboarding · 5". Catalog chưa có nhóm thì liệt kê event như cũ.
• Biểu tượng. Event của Amplitude SDK hiện chữ A màu xanh thay cho tiền tố "[Amplitude] " ("[Amplitude] Application Opened" hiện là "Application Opened"), event của Amplitude Experiment hiện bình thí nghiệm màu tím; giống các biểu tượng trong stream Tracking.
• Tên đầy đủ. Rê chuột lên hàng để xem tên đầy đủ, cũng là tên trong file và tên mà ô tìm kiếm tìm theo.
• Thêm và gỡ. Menu + có Event mới…, Event Amplitude SDK…, User property mới…, Enum mới… và, dưới Rule chung, các mẫu rule. − 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.

Thêm event bằng tay

1. Bấm + dưới danh sách và chọn Event mới….
2. Một popover nhỏ hỏi Tên event. Gõ tên team đọc (tên Display) rồi bấm Thêm (hoặc nhấn Return).
3. Event mới mở trong form. Điền Nhóm và mô tả nếu muốn.
4. Bấm Thêm property… dưới Property, gõ tên property rồi bấm Thêm. Lặp lại cho từng property mà event gửi. Sau đó bấm mũi tên ở cuối hàng của property để đặt Kiểu, Bắt buộc và giá trị cho phép. Xem Giá trị cho phép.

User property mới… và Enum mới… làm tương tự và hỏi Tên user property hoặc Tên enum.

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. Nhãn xám "Chưa thấy trong run nào" hiện dưới ô tên khi có run mà chưa từng thấy event
Nhóm	Vị trí của event trong taxonomy của team (group:). Import taxonomy điền nhóm từ category của event trong sheet. Gõ tên, hoặc chọn một nhóm mà event khác đang dùng từ menu bên cạnh; xoá trống để bỏ nhóm. Nhóm chỉ dùng để xếp danh sách catalog và lọc cửa sổ Tracking, Scout không bao giờ kiểm nó
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
Gợi ý	Những gì run gần nhất cho thấy, xem bên dưới. Chỉ hiện khi có gì để gợi ý

Form không có danh sách rule của riêng event. Các rule chung nêu tên event nằm ở Rule chung.

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, một alert "Rule dùng chung này được dùng bởi …" hỏi Sửa cả N event hoặc Chỉ sửa <event> (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.

Để đổi cách kiểm một property:

1. Trong danh sách Property của event, bấm mũi tên ở cuối hàng của property. Một popover mở ra.
2. Đổi tên, Kiểu hoặc Bắt buộc nếu cần.
3. Dưới phần giá trị cho phép, chọn chế độ trong bảng trên và điền vào.
4. Bấm ra ngoài popover để đóng. Xoá property trong cùng popover xoá property.

Gợi ý từ một run

Khi đã ghi được một run, form của event có thêm mục Gợi ý (kèm số lượng) liệt kê những gì run đó cho thấy. Giá trị lấy từ run ở đầu mục Property chọn run nào.

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. Với property có enum team chưa xác nhận (do import đoán), Không giới hạn giá trị bỏ danh sách đi: property nhận giá trị bất kỳ
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), Warning, Error; Bỏ qua chỉ có trong danh sách với property đã đặt là bỏ qua) 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. Khi danh sách không có giá trị cho nền tảng của run, giá trị đó không được kiểm và run hiện warning enum_platform_missing.

Đượ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 · error
• 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 · error
• lesson_id là tên sai, đúng là lesson id

Rule chung được chia thành các nhóm. Kiểm tra chéo (cross check) so giá trị giữa nhiều event, ví dụ "paywall id phải giống nhau ở Paywall Viewed và Paywall Skipped". Các nhóm là Event chưa có trong catalog và event bị 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

1. Bấm + dưới danh sách và chọn một mẫu trong Rule chung. Popover của rule mở ngay dưới nút. Bạn không bao giờ phải gõ rule: mọi lựa chọn đều lấy từ catalog.
2. Điền các ô chọn. Mỗi ô là một menu Chọn một tên liệt kê event và property của catalog.
3. Đặt Khi sai và, nếu team chưa thống nhất rule, Cần team xác nhận.
4. Bấm Lưu. Nút bị vô hiệu, kèm lý do, cho đến khi điền đủ mọi ô.

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

Khi sai là Error hoặc Chỉ warning. 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.

1. Tìm event dưới App gửi nhưng catalog chưa có · N.
2. Bấm nút dấu cộng ở cuối hàng (tooltip là Thêm vào catalog). Scout 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. Nút tắt cho đến khi Scout tải xong nơi các flow dùng event.

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.

Event Amplitude SDK

Khi app bật autocapture, Amplitude SDK tự gửi một số event: [Amplitude] Application Opened, [Amplitude] Screen Viewed, [Amplitude] Element Interacted… Run bỏ qua những event này khi catalog không liệt kê; khi đã có trong catalog, chúng được kiểm như mọi event.

1. Bấm + dưới danh sách và chọn Event Amplitude SDK…. Sheet "Thêm event Amplitude SDK" mở ra. Sheet liệt kê event theo từng loại autocapture (App lifecycles, Screen views, Deep links, Element interactions, Frustration interactions, Network tracking), mỗi event kèm các property SDK gửi (dấu * là bắt buộc).
2. Tick những event app có bật. Tick tất cả ở tiêu đề một loại tick cả loại đó (thành Bỏ tick tất cả khi đã tick hết). Event mà SDK chỉ gửi trên một nền tảng hiện nhãn như "Chỉ Android" (Fragment Viewed là một ví dụ). Event đã có trong catalog hiện Đã có trong catalog và không tick được.
3. Đọc dòng cuối sheet: "Đã tick N · * bắt buộc · nhóm X · ghi vào <file>". X là nhóm mà các event sẽ vào: nhóm mà các event [Amplitude] … khác đang dùng, nếu không có thì là "Amplitude Default". Muốn đổi thì sửa ô Nhóm của event sau.
4. Bấm Thêm vào catalog. Mỗi event được thêm theo đúng tên SDK, property có sẵn kiểu. Các event có property khác nhau theo nền tảng và phiên bản SDK (element interactions, rage click, dead click, network request) được đặt thêm Property không có trong danh sách: Bỏ qua.

Import taxonomy của bạn

Nếu team giữ kế hoạch event trong một bảng tính, Scout điền catalog từ đó. Bảng tính này là taxonomy.

1. 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.)
2. Trong chế độ catalog, bấm Import… trên thanh nhảy. Sheet "Import taxonomy" mở ra, còn trống: "Chọn file taxonomy".
3. 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. Nếu bạn có project trong Cài đặt → Amplitude, chọn project ở Giá trị từ Amplitude trước, hoặc để nguyên (xem bên dưới).
4. Đợi Scout đọc file. Nếu hiện "Không có thay đổi.", catalog đã khớp file. Nếu hiện danh sách issue, sửa sheet và chọn lại file, hoặc bấm Ghép cột… khi sheet của bạn đặt tên cột khác (xem Tên cột khác).
5. Xem danh sách, bỏ tick những gì không muốn, và đọc dòng cuối sheet: "Đã tick N / M thay đổi (X mới · Y sửa · Z bị xoá) · ghi vào <file>". Cảnh báo về file nằm gọn một dòng trên danh sách; bấm vào để xem hết. Cần xác nhận trên danh sách chỉ hiện các dòng cần kiểm; bấm một dòng để đọc cần kiểm gì và tick thì ghi gì.
6. 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) 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

Tên cột khác

Scout cũng đọc các tên thường gặp khác của một cột, nên sheet không cần theo đúng từng chữ của mẫu:

Cột	Cũng đọc khi tên là
Event Name (Display)	Event Name, Event, Event Display Name, Display Name
Event Properties	Properties, Event Props
Property Name	Property, Property Key, Prop Name
Data Type	Type, Datatype, Value Type, Property Type
Used By Events	Used In Events, Used By
Set By Events	Set By
Sample Values	Sample Value, Examples, Example Values, Allowed Values, Values
Description	Desc, Definition
Event Category	Category, Group

Riêng Name và Events không được đọc thành cột nào: Name có thể là tên event hoặc tên property, còn Events có thể là các event dùng property hoặc các event đặt nó.

Khi sheet dùng tên khác nữa, ghép tay:

1. Bấm Ghép cột…, cạnh Chọn File… hoặc dưới danh sách issue.
2. Ở Events, chọn Tab trong bảng tính chứa danh sách event, rồi chọn cột cho từng trường. Trường có dấu * là bắt buộc; Áp dụng chỉ bật khi đã ghép đủ.
3. Làm tương tự cho Event property và User property, hoặc để Không có trong file này.
4. Bấm Áp dụng. Scout đọc lại file với các cột này.

Scout nhớ cách ghép cho catalog này và dùng lại mỗi lần bạn import vào nó; dòng "· cột đã ghép tay" cạnh tên file cho biết điều đó. Đặt lại quay về tìm cột theo tên.

Mỗi event lấy category của nó làm group:: ô ở cột Event Category (hoặc Category), hoặc ở cột không có tiêu đề nơi các dòng tiêu đề nhóm nằm (như "Onboarding" cạnh từng event dưới ONBOARDING). Event có ô category trống thì lấy dòng tiêu đề nhóm phía trên nó. Import lại sẽ chuyển nhóm cho event có category đã đổi, và giữ nguyên nhóm khi sheet không ghi category.

Property kiểu string có Sample Values trông như một danh sách cố định (car, cdl, motorcycle) sẽ được tạo enum với các giá trị đó, đánh dấu cần xác nhận. Nếu Sample Values chỉ là ví dụ (id, tên, địa điểm, mã ngắn), property đó được import là string, không giới hạn giá trị.

Chi tiết kỹ thuật: khi nào Sample Values chỉ là ví dụ

Sample Values chỉ được coi là ví dụ khi property là id, tên hay địa điểm (từ cuối của tên là id, ids, name, token, url, email, city, country, carrier, code, number, key, uuid, title, text, message, path hoặc version), khi một giá trị trông như id (có từ ba chữ số liền nhau, như lesson_001), hoặc khi mọi giá trị là mã ngắn (CA, TX, USD, EUR): property đó được import là string, không giới hạn giá trị.

Giá trị từ Amplitude. Khi Cài đặt → Amplitude có project kèm Secret key, sheet import có menu Giá trị từ Amplitude dưới hàng chọn file. Các lựa chọn là Tắt và từng project. Scout chọn sẵn project duy nhất có Forward tắt, nếu có đúng một; không có hoặc có nhiều thì bắt đầu ở Tắt. Scout nhớ lựa chọn theo từng catalog. Khi đã chọn một project, mỗi enum đoán từ Sample Values được đối chiếu với các giá trị project này lưu trong 30 ngày qua:

Amplitude thấy	Import
Hơn 20 giá trị	Không ghi enum: "không giới hạn giá trị"
Chỉ các giá trị trong danh sách	Ghi enum không cần xác nhận, mục đó tick được ngay
Có giá trị ngoài danh sách	Giữ danh sách của sheet, nêu tên các giá trị kia ("Amplitude còn thấy CDL, auto"), cần xác nhận: đó có thể là giá trị mới hoặc app gửi sai
Không có gì, hoặc không đọc được	Giữ phần đoán từ sheet, cần xác nhận

Giá trị từ Amplitude không bao giờ tự thành danh sách, nên giá trị app gửi sai không được import cho phép. Đọc giá trị của một sheet lớn chậm (Scout ngừng hỏi Amplitude sau khoảng 150 giây và hỏi nốt phần còn lại ở lần sau). Kết quả được giữ 6 giờ. Ghi vào catalog không bao giờ hỏi Amplitude: nó ghi đúng những gì bản xem trước đã hiện, nên bản xem trước cũ hơn 6 giờ phải mở lại (chọn lại file).

Mỗi dòng thành một event, đặt tên theo Event Name (Display); dòng không có tên Display bị bỏ ra và được liệt kê trong danh sách issue kèm số dòng. Import lại sẽ khớp event theo tên đó.

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.

Chữ gạch ngang trong file .xlsx được coi là team đã xoá. Một dòng bị gạch trong ô danh sách sẽ bị bỏ qua, và hàng có tên bị gạch cũng bị bỏ qua, nên event đó hiện ở Bị xoá khỏi sheet. Property bị gạch trong ô Event Properties của một event được đề xuất xoá khỏi event đó trong catalog, dưới dạng thay đổi cần xác nhận (rule của nó bị xoá theo; rule dùng chung với event khác thì để bạn tự sửa). Property chỉ vắng mặt trong sheet thì vẫn được giữ. Danh sách issue cho biết mỗi tab bỏ qua bao nhiêu mục bị gạch. File .csv và .tsv không lưu định dạng, nên dùng file .xlsx cho việc này.

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) và user property do Amplitude đặt. Chúng không có ô tick. Mục này gập sẵn cho đến khi bạn mở

Event mà Amplitude SDK tự gửi (Source "Amplitude SDK", như Application Opened) được import theo tên SDK gửi, [Amplitude] Application Opened, để run kiểm property của chúng. build, version và from background của sheet thành [Amplitude] Build, [Amplitude] Version và [Amplitude] From Background của SDK; property riêng của app giữ nguyên tên.

Khi sheet có category, mỗi mục được chia theo category (Onboarding, Paywall…), mỗi nhóm gập/mở riêng, Không có nhóm ở cuối; event bị xoá nằm dưới nhóm của nó trong catalog. 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 danh sách 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àng đó ghi lý do bằng chữ cam, bên dưới là cần kiểm gì và tick thì ghi gì. Tick khi team đã thống nhất. Tên lặp thì tick cũng không ghi gì: xoá dòng lặp trong sheet. 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.

Chi tiết kỹ thuật

Hai mục sau dành cho dev viết YAML trực tiếp hoặc dùng script và plugin.

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.
• Không có ingested. Event có key ingested không load được; lỗi nêu số dòng. Xoá key đó.

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ó:

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

AI CLI có plugin scout 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
POST /api/tracking/spec/rename-enum	Đổi tên một enum 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.