Tracking

Kiểm các event Amplitude mà bản QA của app gửi khi chạy flow: khai báo event trong flow, xem kết quả ngay tại dòng.

Astra Scout kiểm các event Amplitude mà bản QA của app gửi trong lúc chạy flow. Bạn không cần đợi dữ liệu lên Amplitude.

Hai file làm việc cùng nhau:

File	Chứa
Flow	Mỗi thao tác phải gửi event nào: các step `assertEvents` ngay dưới thao tác, và header `tracking`
Catalog (`tracking-specs/<app>.yaml`)	Các rule cho mọi run: event, property, giá trị cho phép và rule chung. Xem Catalog tracking

QA build of your app (Amplitude SDK, serverUrl = Astra Scout)
   │  POST /2/httpapi
   ▼
astra-scout-server, port 5051
   │  attaches events to the flow run in progress
   ▼
Your flow: ✓ or ✕ at each assertEvents line, plus the Tracking window for the whole run

Trỏ bản QA của app vào Astra Scout

Astra Scout mở một listener giả lập HTTP API của Amplitude trên localhost:5051 (endpoint /2/httpapi và /batch, cùng endpoint cũ nhận form-encoded). Chỉ đặt serverUrl của SDK trong bản QA hoặc debug, không bao giờ trong bản release, và flush event ngay (flushQueueSize: 1, cùng flushIntervalMillis ngắn như 1000) để event hiện ra khi step đã gửi nó còn đang trên màn hình.

Các URL dùng được nằm trong cửa sổ Tracking (Window → Tracking, Shift+Cmd+T): mở menu Hành động (nút …) và xem mục SDK serverUrl · N received. Mỗi URL có một mục Sao chép ….

App chạy ở đâu	serverUrl
iOS Simulator trên cùng Mac	`http://127.0.0.1:5051/2/httpapi`
Android emulator	`http://10.0.2.2:5051/2/httpapi`
Android thật qua USB	Chạy `adb reverse tcp:5051 tcp:5051`, rồi dùng `http://127.0.0.1:5051/2/httpapi`
iPhone hoặc Android thật qua Wi-Fi	`http://<tên Mac>.local:5051/2/httpapi` hoặc `http://<IP LAN của Mac>:5051/2/httpapi`; mục SDK serverUrl trong menu Hành động của cửa sổ Tracking liệt kê cả hai. Nhận event từ device trong mạng trong Settings → Amplitude mặc định đã bật; server CLI thì dùng `--tracking-addr 0.0.0.0:5051` (hoặc `SCOUT_TRACKING_ADDR`)

Một bản QA cho mọi máy Mac (iOS)

Trên iOS, launchApp truyền cho app launch argument scoutServerUrl: địa chỉ listener của chính máy Mac này, trên đường dẫn riêng của device (http://127.0.0.1:5051/d/<mã>/2/httpapi trên simulator, http://<tên Mac>.local:5051/d/<mã>/2/httpapi trên iPhone). Bản QA nào đọc giá trị này (iOS đưa launch argument vào UserDefaults) sẽ gửi event về đúng máy Mac đang chạy flow, nên một bản build dùng được cho mọi tester; Astra Scout cũng chỉ gắn các event đó vào run trên đúng device, điện thoại khác trong mạng không lẫn vào run của bạn. Flow tự đặt scoutServerUrl trong launchApp: arguments: thì giữ giá trị của flow.

swift

// Chỉ bản QA: ưu tiên địa chỉ Astra Scout truyền vào lúc mở app.
if let scout = UserDefaults.standard.string(forKey: "scoutServerUrl"), !scout.isEmpty {
    serverUrl = scout
}

Event gửi tới /2/httpapi thường (serverUrl cố định) vẫn được gắn vào run đang diễn ra, bất kể từ device nào.

Tắt nhận event từ mạng khi dùng mạng không tin cậy

Listener chỉ nhận event, nhưng máy khác trong cùng mạng cũng gửi vào được. Trên mạng công cộng, tắt Nhận event từ device trong mạng; simulator vẫn chạy bình thường. Công tắc có hiệu lực sau khi server khởi động lại (Khởi động lại server ngay).

HTTP thường bị App Transport Security của iOS và Android 9 trở lên chặn mặc định, nên bản QA cần ngoại lệ network-security cho các địa chỉ này.

Kiểm một run

Mở một workspace. Astra Scout tìm catalog trong tracking-specs/ của workspace và tối đa ba thư mục cha. Mỗi app có một catalog, ví dụ tracking-specs/mydmv.yaml.
Chạy flow bằng Chạy test (Cmd+R) hoặc Chạy tất cả test (Shift+Cmd+R).
Tab Tracking của runner tóm tắt run mới nhất: kết luận, số đếm, issue đầu tiên và các API key mà event mang theo. Bấm vào issue, hoặc Mở cửa sổ Tracking, để xem cả run.

Cửa sổ Tracking (Window → Tracking, Shift+Cmd+T) hiện một run mỗi lần và theo run mới nhất cho đến khi bạn chọn run khác. Cửa sổ không tự mở.

Phần	Hiện
Runs (thanh bên)	Mỗi run đã ghi, kèm flow, nền tảng, số event và dấu pass, warning hoặc fail
Event stream	Các event của run theo thời gian, xen các step của flow (`launchApp`, `tapOn`…) để thấy step nào gửi event nào. Step `assertEvents` hiện kết quả. Run do agent khởi động qua MCP hoặc qua API cũng hiện các step, ngay khi chúng chạy. Mỗi event hiện issue của nó (nếu có); khoảng nghỉ từ một giây trở lên hiện thành khoảng trống
Thanh kiểm tra	Khi chưa chọn event: kết luận (biểu tượng trạng thái, Pass, Warning hoặc Fail, và "N error · N warning · N event · nền tảng"), dòng Catalog, Kiểm tra trong flow, các Issue (ẩn khi trống; bấm một mục để xem event của nó), mục Amplitude, mục Event từ server, user property cuối run và các Rule. Khi chọn một event: property của nó, các user property nó đặt, và toàn bộ user property tại event đó

Thanh dưới stream có Hiện step của flow, Ẩn event SDK (gộp $identify và các event [Amplitude] …, trừ khi kiểm tra đánh dấu một event), Chỉ hiện mục có issue và ô lọc. Menu Hành động (nút …) trên toolbar có Kiểm tra lại, Xuất JSON…, Nền tảng (Tự động đọc từ event) và Xoá các run đã ghi.

Khai báo kiểm tra trong flow

Đặt phần kiểm ngay dưới thao tác gửi event. Flow cũng nêu catalog của nó trong header tracking trước dấu ---:

yaml

appId: ${APP_ID}
tracking:
  spec: mydmv                  # tracking-specs/mydmv.yaml; optional when the workspace has one catalog
  forbid: [Purchase Initiated, Purchase Completed, Purchase Failed]   # events the whole run must not send
---
- tapOn: "Car"
- tapOn: "Continue"
- assertEvents:
    - License Selected:
        license type: car
        placement: onboarding

Key header	Ý nghĩa
`spec`	Catalog, viết là tên không có đuôi hoặc đường dẫn tương đối
`forbid`	Các event run không được gửi, ở bất kỳ step nào

Chỉ header của flow cấp cao nhất được tính. Key không hợp lệ dưới tracking, hoặc spec không tìm ra file, làm flow không hợp lệ. Dòng Catalog trong thanh kiểm tra của cửa sổ Tracking cho biết run được kiểm tra theo catalog nào. Khi workspace có nhiều catalog, dòng này là một menu: mặc định là Catalog của flow, và catalog chọn ở đó áp dụng cho file flow đó.

Ba cách viết

yaml

- assertEvents: [Onboarding Step Viewed, Profile Created]   # names only
- assertEvents:                                             # names with values
    - License Selected:
        license type: car
    - Paywall Viewed: { placement: onboarding }
- assertEvents:                                             # with a timeout
    timeout: 8000
    events:
      - Paywall Viewed: { placement: onboarding }

Giá trị property là giá trị thường, phải bằng đúng cái app đã gửi, hoặc một map điều kiện (in, min, max, regex, type). Danh sách đầy đủ nằm ở tham chiếu assertEvents.

Một lần kiểm hoạt động thế nào

Cửa sổ thời gian. Lần kiểm xét các event từ 500 ms trước thao tác cuối cùng đụng tới app (chạm, gõ, vuốt, launchApp). Lệnh chờ và lệnh assert không làm nó dịch chuyển. Vậy tapOn rồi assertEvents sẽ kiểm event của lần chạm đó.
Timeout. Step chờ tối đa timeout mili giây (mặc định 5000) cho event chưa đến. Thời gian chờ tính từ chính step assertEvents.
Mỗi event một lần. Mỗi event được liệt kê phải khớp một event app đã gửi. Event mà một assertEvents đã khớp thì assertEvents sau không dùng lại. Thứ tự trong cùng một step không quan trọng.
Sau một block. assertEvents ngay sau runFlow hoặc repeat kiểm mọi event block đó đã gửi.
Nhánh. assertEvents trong runFlow có when chỉ được kiểm khi nhánh đó chạy. Dòng chưa từng chạy thì không có kết quả.
Fail không dừng flow. Event thiếu hoặc sai giá trị làm step fail và nói rõ vì sao; các lệnh tiếp theo vẫn chạy, và run kết thúc ở trạng thái fail.
forbid. Bất kỳ event nào trong danh sách, ở bất kỳ lúc nào, làm lần kiểm flow:forbidden fail.
Mọi event còn được kiểm theo catalog, dù có nêu trong flow hay không: tên chưa có trong catalog, kiểu sai, thiếu property bắt buộc, rule chung.

Event SDK như $identify và [Amplitude] … bị assertEvents bỏ qua.

Gõ trong editor

Trong step assertEvents, editor gợi ý tên event từ catalog của flow, rồi đến các property của event đó (property bắt buộc lên đầu), rồi đến giá trị cho phép của property. Chọn một tên có property bắt buộc sẽ thêm sẵn một dòng cho mỗi property.

Kết quả trong editor

Sau khi chạy, editor hiện kết quả của từng assertEvents ngay chỗ bạn viết. Kết quả chỉ hiện khi file chưa đổi kể từ lúc chạy; sửa file thì kết quả ẩn đến run sau.

Ở đâu	Hiện
Số dòng	✓ pass, ✕ fail, ▲ warning (step `optional` hoặc bị ngắt). Dòng chạy nhiều lần hiện kết quả xấu nhất
Cuối dòng fail	Một banner ngắn có thông báo, ví dụ event nào không bao giờ đến
Bảng run	Dưới mỗi step `assertEvents`, một hàng cho mỗi event mong đợi: đã khớp kèm thời gian, hoặc issue
Danh sách Kiểm tra trong flow	Trong tab Tracking và cửa sổ Tracking: một hàng cho mỗi run của một dòng `assertEvents`. Mũi tên (Xem trong flow, cũng có trong menu chuột phải của hàng) mở file ở dòng đó

Bấm dấu ✓ ✕ ▲ hoặc banner để mở tab Event trong thanh kiểm tra. Tab không tự mở khi bạn di con trỏ.

Phần của tab Event	Hiện
In this flow	Các giá trị bạn đã viết. Chọn giá trị cho phép từ menu, tick boolean, gõ giá trị khác, thêm hoặc xoá property, đặt timeout. Mọi sửa đổi đi qua văn bản nên `⌘Z` hoàn tác được. Điều kiện như `{ in: [1, 2] }` chỉ đọc ở đây: sửa trong văn bản
Các rule được kiểm tra tự động	Các rule của catalog áp dụng cho những event này, viết thành câu thường, mỗi rule có Mở trong catalog. Event mà catalog chưa có thì được nêu rõ
Run mới nhất	Kết quả, thời gian, timeout, phần khớp hoặc issue của từng event mong đợi, và các event nhận được trong cửa sổ cùng property của chúng
Cách sửa (dòng fail)	Các cách sửa nhanh, bên dưới

Cách sửa nhanh

Nút	Làm gì
Đổi tên trong flow	Menu các tên event app đã gửi, gần nhất lên đầu. Chọn một tên sẽ viết lại tên trong flow
Thêm vào catalog	Thêm event mà catalog chưa có. Hỏi trước, nêu tên event và file catalog
Báo bug lên Jira…	Mở báo cáo Jira với error của dòng này đã chọn sẵn

Gán event từ một run

Bạn không cần tự gõ assertEvents. Chạy flow một lần và để Scout viết phần kiểm từ những gì app đã gửi.

Chạy flow một lần. Phải thiết lập xong phần ghi event (xem ở trên).
Đọc thanh thông tin. Khi run mới nhất của flow đang mở có event mà flow chưa kiểm, một thanh hiện trên editor: "Run 14:02 nhận 31 event, 12 event chưa có trong flow." Thanh còn nói có bao nhiêu event sai rule. Ẩn lần này đóng thanh cho run đó.
Xem các số màu xám. Mỗi dòng thao tác có ◉ N, số event app đã gửi sau thao tác đó. Dòng có con trỏ nói rõ hơn. Bấm vào số để xem các event đó trong tab Event, nơi Thêm tên event và Thêm kèm giá trị ghi từng event. Bấm chuột phải một dòng thao tác và chọn Thêm kiểm event… để mở cùng màn hình đó.
Mở sheet. Bấm Gán event vào flow…. Mỗi event được xếp dưới thao tác chạy ngay trước nó.
Tick và ghi. Chọn các event muốn kiểm và bấm Ghi vào flow.

Sheet hoạt động như sau:

Run nào. Run của flow này chọn bất kỳ run nào của file này.
Tick sẵn. Event đúng rule của catalog, và event catalog chưa có (kèm warning). Event sai rule thì không tick. Menu … cạnh ô tìm kiếm có Chọn mọi event đúng rule và Bỏ chọn hết để đổi nhiều mục cùng lúc.
Giá trị. Ghi giá trị là Giá trị giống nhau ở mọi run hoặc Chỉ tên event. Với lựa chọn đầu, Scout chỉ ghi các giá trị giữ nguyên qua các run và bỏ id, giờ, ngày, đánh dấu "không ghi".
Event SDK ($identify, [Amplitude] …) bị bỏ ra và không có ô tick.
Sai thao tác. Nếu Scout đoán sai thao tác, Thao tác chuyển event sang thao tác khác.
Event đến trễ. Event đến sau thao tác hơn 5 s được ghi timeout dài hơn, và hàng đó cho biết.
Cuối flow. Event gửi sau khi flow kết thúc nằm dưới Sau khi flow kết thúc. Chúng không có ô tick và không được ghi: không step nào trong flow kiểm được chúng.
Subflow. Thao tác trong subflow runFlow: file: được assertEvents ngay sau dòng runFlow trong flow đang mở. File subflow không bị đổi. Thao tác trong runFlow có when được assertEvents bên trong nhánh đó.
Xem trước. Mở Xem trước rồi chuyển giữa Event đang chọn và Toàn bộ thay đổi để xem các dòng trước khi ghi.
Kiểm sau khi ghi. Chạy lại flow sau khi ghi để kiểm chạy flow lần nữa.

Scout ghi vào văn bản editor đang mở, thành một thay đổi: ⌘Z hoàn tác cả lần gán, còn comment và các dòng khác không bị đụng tới. Nếu một dòng thao tác đã đổi kể từ run, event của nó hiện "dòng đã đổi, chạy lại flow".

Một run được kiểm theo gì

Check id	Đến từ	Áp dụng khi
`schema:`, `global:`	Catalog: `events`, `enums`, `user_properties`, `global_rules`	Luôn luôn, với mọi event của run
`cross:*`	`cross_checks` trong catalog	Luôn luôn. N/A khi các event cần so sánh không có trong run
`assert:<file>:<line>`	Một cái cho mỗi dòng `assertEvents`. Fail khi bất kỳ run nào của dòng fail. Step `optional` fail chỉ là warning	Dòng đó đã chạy. Dòng chưa chạy thì không có hàng
`flow:forbidden`	`tracking.forbid` trong header của flow	Header có mục `tracking`. N/A khi `forbid` trống
`userprop:<property>@<event>`	`user_property_rules.rules` trong catalog	Event kích hoạt (`after`) có trong run. N/A nếu không có
`identity:*`	`identity` trong catalog	Định dạng `device_id` và `user_id`: luôn luôn. Rule đăng nhập: có event đăng nhập trong run. Rule đăng xuất: có event đăng xuất trong run
`server:<id>`	`server_checks` trong catalog	Event `after` có trong run. N/A nếu không có
`amplitude:*`	Đọc lại từ Amplitude	Xem Kết quả từ Amplitude

Rule không áp dụng là N/A, không phải pass. Run mà mọi rule đều N/A thì cả run là N/A.

Danh sách Kiểm tra trong flow có một hàng cho mỗi lần thực thi assertEvents: trạng thái, tên event, lý do khi fail, và "dòng N". Bấm một hàng sẽ chọn event của nó trong stream. Lỗi assertEvents không lặp lại trong Issue, vì hàng ở đây đã hiện nó.

Khi run còn đang diễn ra, assertEvents còn đang chờ, một user property được đặt hoặc giá trị cuối chưa đến sẽ hiện Đang chờ thay vì fail, và kết quả là Đang chờ cho đến khi run kết thúc hoặc một rule fail. Event hoặc property sai thì fail ngay.

Rule có severity error làm lần kiểm fail; warn chỉ ghi nhận. Event đến ngoài mọi run nằm dưới Event ngoài mọi run. Dùng Xuất JSON… để đính kèm spec, report và event vào ticket, và Xoá các run đã ghi để đặt lại (cả hai nằm trong menu Hành động).

Để đổi rule, xem Catalog tracking. Các phần dưới đây nói về những kiểm tra nằm trong catalog nhưng cần nhiều hơn một rule property.

Rule cho user property

Catalog cũng kiểm được các user property mà app đặt (các op Identify của Amplitude như $set, $setOnce, $add, $unset). Thêm mục user_property_rules. Mỗi rule cần một event after: rule chỉ chạy khi event đó có trong run, nếu không là N/A.

yaml

user_property_rules:
  severity: warn                 # default for the rules below
  forbid_ops: ["$clearAll"]      # ops that must not appear
  rules:
    - property: access level
      op: "$set"                 # $set, $setOnce, $add, $unset, $append, $prepend, $preInsert, $postInsert, $remove or any
      after: { event: Purchase Completed, within_ms: 10000 }
      value: { in: [trial, premium] }
      final: { equals: premium } # value after applying every op of the run
    - property: first open date
      op: "$setOnce"
      after: { event: Onboarding Started }
      set_once_stable: true      # never overwritten by $set, $unset or $clearAll in the run
      amplitude: final           # also check the value stored in Amplitude
    - property: onboarding paywall status
      op: "$set"
      after: { event: Paywall Skipped, where: { placement: onboarding } }   # same conditions as assertEvents
      value: { equals: skipped }
      persist: true              # still stored after a new session

Key	Ý nghĩa
`property`, `op`	Property và phép toán cần tìm (`op` mặc định là `any`)
`value`	Ràng buộc cho giá trị của mỗi op khớp, giống property của event, thêm `type`, `regex`, `max` và `from_prop`
`after`	Bắt buộc. Event kích hoạt rule; `where` giới hạn cho event có các giá trị property này. Op phải đến trong vòng `within_ms` (mặc định 10000) sau event đã nêu, hoặc tối đa `before_ms` (mặc định 1000, `-1` là tắt) trước nó: app thường identify ngay trước event mà nó đặt property cho
`count`	Có bao nhiêu op khớp (mặc định ít nhất 1)
`final`	Ràng buộc cho giá trị sau khi gộp mọi op của run
`forbid_ops`	Các op không được xuất hiện, như `$clearAll`
`set_once_stable`	Property `$setOnce` không bị op khác đổi trong run
`persist`	Property còn lại sang session mới (kiểm trên Amplitude)
`severity`	`error` hoặc `warn` cho rule đó. Rule chỉ kiểm trên payload đã bắt mặc định là `error`, rule cần Amplitude mặc định là `warn`

Mỗi rule có id userprop:<property>@<event>. Rule đánh dấu needs_confirmation: true vẫn là warning cho đến khi team xác nhận.

Catalog user property

Thêm user_properties ở đầu spec (cạnh events) để kiểm mọi giá trị app đặt, giống property của event: type, enum hoặc enum_ref, regex, min, not_empty, forbidden. User property mà catalog không liệt kê sẽ theo global_rules.unknown_user_properties (ignore, warn là mặc định, hoặc error). Mỗi property và mỗi giá trị chỉ được báo một lần, vì SDK lặp lại $setOnce ở mọi event.

yaml

user_properties:
  days until exam: { type: integer }
  access level: { type: string, enum_ref: access level }
global_rules:
  unknown_user_properties: { severity: warn }

Lựa chọn tương tự có cho từng event với property của event: extra_properties: ignore | warn | error trên event (mặc định là global_rules.unknown_properties). Khi property có required: true, ignore nghĩa là "những property này phải có, còn lại không quan trọng" và error nghĩa là "đúng những property này, không hơn".

Mục identity của catalog kiểm user_id và device_id quanh lúc đăng nhập, và xem Amplitude có gộp profile ẩn danh vào profile của user không:

yaml

identity:
  login_event: [Sign In Completed, Signup Completed]   # a name or a list
  device_id: stable              # or reset_on_logout (needs logout_event)
  user_id: { regex: "^[0-9a-f]{24}$" }
  amplitude_merge: true          # default when login_event is set

Kiểm tra định dạng device_id và user_id luôn chạy. Kiểm tra đăng nhập chạy khi có event đăng nhập trong run, và kiểm tra đăng xuất chạy khi có event đăng xuất. Gộp lại, chúng kiểm rằng không event nào mang user_id trước login_event, event sau đó thì có (châm chước 2 event hoặc 10 s), user_id không đổi nếu không đăng xuất và đúng định dạng, và với logout_event thì nó biến mất sau khi đăng xuất. amplitude_merge đọc lại user từ Amplitude và báo warning khi device_id mà app có trước lúc đăng nhập không nằm trong profile của user đó: Amplitude giữ hai profile cho một người.

Kết nối Amplitude

Ghi event không cần tài khoản Amplitude. Để kiểm thêm cái Amplitude thực sự đã lưu, thêm project của bạn trong Settings → Amplitude (Thêm project…):

Trong Amplitude, mở Settings → Projects → project của bạn → General và sao chép API Key và Secret Key.
Trong Astra Scout, thêm project với cả hai key. Vùng (region) mặc định là Tự động: Kiểm tra kết nối thử US, rồi EU, và giữ vùng nhận key. Bạn vẫn có thể tự chọn US hoặc EU.
Đặt Chuyển tiếp event tới Amplitude. Mục này tắt sẵn cho từng project. Khi bật, một hộp thoại hỏi bạn xác nhận. Chỉ bật khi project dùng cho Staging: event ghi được trong run cũng được gửi tới Amplitude để đọc lại. Giữ tắt cho Production: dữ liệu test không được đi vào đó. Với Production, dùng tra cứu chỉ đọc.
Có thể điền ID project Amplitude (chỉ chữ số, ví dụ 123456, lấy từ Settings → Projects trong Amplitude). Scout không đọc được nó từ key. Nếu Amplitude báo một project cho run, form gợi ý Amplitude báo project N, dùng ID này?. Form không bao giờ tự điền ô này.

Mỗi run dùng project có API key mà app đã gửi, nên bạn không phải chọn project cho từng run.

Một project Amplitude có thể có nhiều API key (Organization settings → API Keys liệt kê theo project). Khi các bản build của app gửi bằng key khác key bạn đã đưa cho Scout, ví dụ key legacy của project, hãy thêm nó vào Key của app trong cùng form project. Chỉ cần key, không cần Secret key. Run gửi bằng API key hoặc bất kỳ key của app nào thuộc về project đó; Scout vẫn đọc Amplitude bằng API key và Secret key. Form chỉ hiện key của app bằng 4 ký tự cuối.

Sai project Amplitude

Khi spec nêu project của nó (source.amplitude_project_id) và ID project đã đặt trong Settings → Amplitude, Scout so hai giá trị cho mỗi API key app đã gửi. Không khớp là rule amplitude_wrong_project với severity error: thông báo nêu cả hai ID project và không bao giờ nêu key. Việc kiểm chạy cục bộ, không cần mạng. Kết quả là na, kèm lý do, khi spec không có source.amplitude_project_id, run không gửi API key nào qua Scout, key không có trong Settings → Amplitude, hoặc project đó chưa có ID project.

Kết quả từ Amplitude

Mục Amplitude nêu từng API key run đã gửi bằng 4 ký tự cuối và project nó khớp trong Settings → Amplitude (theo API key hoặc key của app), hoặc báo key chưa có ở đó, kèm Mở cài đặt Amplitude…. Dưới các key là các hàng Đã chuyển tiếp ("N đã gửi · N fail · N bỏ qua"), Trạng thái và User, cùng hai nút Tra cứu người dùng… và Kiểm tra trên Amplitude ở cuối mục.

Danh sách Rule hiện trước các rule fail, warning hoặc đang chờ. Các rule pass được gộp dưới "Cả N rule đều pass".

Sau run Staging, Scout đọc lại test user từ Amplitude và điền kết quả cho các rule dùng amplitude, persist và set_once_stable. Amplitude có thể mất một lúc để ingest event, nên Scout poll tối đa khoảng 2 phút. Các rule này hiện trong cửa sổ Tracking cạnh các rule khác, và trong report. Kiểm tra trên Amplitude đọc lại run lần nữa.

Kết quả	Ý nghĩa
`na`	Chưa kiểm: key chưa có project Amplitude nào được cấu hình, việc đọc lại chưa xong, hoặc không có gì để so sánh
`amplitude_unavailable` (warn)	Không đọc được Amplitude (sai key, rate limit hoặc timeout). Không bao giờ tính là pass

Với run không được chuyển tiếp (Production), dùng Tra cứu người dùng… trong cửa sổ Tracking và tra một tài khoản test theo user_id hoặc device_id. Nó chỉ đọc các property đã lưu và các event mới nhất. MCP tool amplitude_user_lookup làm điều tương tự từ terminal.

Event từ server

Một số event do backend gửi, không phải app (ví dụ Trial Started sau khi Apple hoặc Google xác nhận giao dịch). Thêm danh sách server_checks vào catalog. Mỗi check bắt đầu từ một event after: khi event đó có trong run, Scout tìm event của backend trên Amplitude sau run.

yaml

server_checks:
  - id: trial_started          # optional; the default is the after event. Ids are unique
    after: { event: Purchase Completed }
    wait_minutes: 15           # default 15, at most 60
    severity: warn             # default warn
    expect_one_of: [Trial Started, Subscription Started]
    props:
      $revenue: { type: number, min: 0 }

Key	Ý nghĩa
`id`	Tên của check; hàng của nó là `server:<id>`
`after`	Event trong run kích hoạt check. Không có nó trong run thì check là N/A
`wait_minutes`	Event được phép mất bao lâu để xuất hiện (mặc định 15, từ 1 đến 60)
`severity`	`error` hoặc `warn` nếu event thiếu hoặc sai (mặc định `warn`)
`expect_one_of`	Tên event. Một trong số đó phải xuất hiện cho test user, sau event kích hoạt
`props`	Ràng buộc cho property của event đó, giống property của event

Event từ backend được tra theo user_id. Khi event app gửi trong run không có user_id (tester chưa đăng nhập), Scout dùng user mà Amplitude đã gắn với device của run; kết quả ghi rõ user_id đã dùng. Event app gửi trong run không bao giờ được tính (so theo insert_id); event từ backend có thể mang device_id của app.

Scout đọc các event mới nhất của test user ở phút thứ 1, 2, 4 và 8 sau run, rồi cứ 8 phút một lần cho đến hết wait_minutes. Mọi check của một run dùng chung một vòng poll; mỗi check có thời gian chờ và kết quả riêng. Mỗi lần tra cứu tính vào rate limit của Amplitude, mà Scout dùng chung cho mỗi project (4 request một phút), nên một check mặc định tốn khoảng 4 request. Khi bị rate limit, Scout chờ rồi thử lại. Các hàng hiện dưới Event từ server trong thanh kiểm tra của cửa sổ Tracking:

Kết quả	Ý nghĩa
Đang chờ	Vẫn đang tìm: Scout hiện lần thử thứ mấy và khi nào kiểm tiếp
`pass`	Có event khớp đến và property đúng
`fail` hoặc `warn`	Không có event khớp trong `wait_minutes` (theo severity của spec). Thông báo liệt kê các event khác Amplitude có sau event kích hoạt, để biết backend đã gửi gì thay vào
`na`	Chưa kiểm, kèm lý do: event kích hoạt không có trong run, run không có `user_id` hoặc `device_id` nào biết được, chưa cấu hình project Amplitude, hoặc việc đọc lại bị ngắt
`amplitude_unavailable` (warn)	Không đọc được Amplitude (sai key hoặc bị từ chối truy cập). Không bao giờ tính là pass

Kết quả chỉ giữ trong bộ nhớ, giống các run. Sau khi server Studio khởi động lại, check đang chờ hiện na ("server check interrupted, re-run"): hãy chạy lại.

So sánh iOS ↔ Android

Để xem hai app có gửi cùng tracking không, chạy cùng một file flow trên iOS và Android, rồi bấm So sánh trên toolbar của cửa sổ Tracking. Sheet hiện flow và chỉ liệt kê các run của file đó. Chọn một Run iOS và một Run Android (run đã xong mới nhất của mỗi bên được chọn sẵn) rồi bấm So sánh. Run của các file flow khác nhau bị từ chối.

Các tab Thứ tự, Events và User property hiện mỗi hàng là Giống nhau, Khác nhau, Chỉ có trên iOS hoặc Chỉ có trên Android. Dùng Hiển thị → Khác biệt để ẩn các hàng giống nhau. Scout không so giá trị: chỉ so thứ tự event, tên property và kiểu của chúng (string, number, boolean, list, object). Kết quả chỉ để tham khảo: nó không thêm finding nào vào lần kiểm hay report.

Các mục chỉ có trên một nền tảng có thể bỏ qua trong catalog:

yaml

parity:
  ignore_events: [Notification Permission Requested]
  ignore_props: [haptics enabled]   # also applies to user properties

Event nội bộ của SDK ([Amplitude] …) luôn bị bỏ ra.

Quyền riêng tư

API key và Secret key được lưu mã hoá trên Mac của bạn. Chúng không bao giờ xuất hiện trong report, log, bản xuất hay output MCP. Lịch sử Scout giữ trên đĩa để so sánh các run chỉ nhận diện user bằng hash, và các mục cũ được dọn tự động.

Từ terminal

MCP tool check_tracking (skill check-tracking của plugin) kiểm event của một run theo spec nêu trong header của flow. specPath là không bắt buộc; kết quả là spec_not_found khi không tìm ra catalog nào. Report liệt kê header flow và một hàng cho mỗi dòng assertEvents. Nó cũng gồm các hàng event từ server, có thể còn đang chờ ngay sau run: gọi lại sau. compare_tracking_runs làm cùng phép so sánh như So sánh iOS ↔ Android… (không bắt buộc flowPath, specPath, iosFlowId, androidFlowId; mặc định là run đã xong mới nhất của mỗi nền tảng cùng file flow). Xem Plugin scout.

Tracking ​

Trỏ bản QA của app vào Astra Scout ​

Một bản QA cho mọi máy Mac (iOS) ​

Kiểm một run ​

Khai báo kiểm tra trong flow ​

Ba cách viết ​

Một lần kiểm hoạt động thế nào ​

Gõ trong editor ​

Kết quả trong editor ​

Cách sửa nhanh ​

Gán event từ một run ​

Một run được kiểm theo gì ​

Rule cho user property ​

Catalog user property ​

Đăng nhập và profile Amplitude ​

Kết nối Amplitude ​

Sai project Amplitude ​

Kết quả từ Amplitude ​

Event từ server ​

So sánh iOS ↔ Android ​

Quyền riêng tư ​

Từ terminal ​

Tracking

Trỏ bản QA của app vào Astra Scout

Một bản QA cho mọi máy Mac (iOS)

Kiểm một run

Khai báo kiểm tra trong flow

Ba cách viết

Một lần kiểm hoạt động thế nào

Gõ trong editor

Kết quả trong editor

Cách sửa nhanh

Gán event từ một run

Một run được kiểm theo gì

Rule cho user property

Catalog user property

Đăng nhập và profile Amplitude

Kết nối Amplitude

Sai project Amplitude

Kết quả từ Amplitude

Event từ server

So sánh iOS ↔ Android

Quyền riêng tư

Từ terminal