Cài đặt

Cấu hình tự động lưu, ngôn ngữ, Android, Team ký app, AI, Jira, Amplitude và App Store Connect, đặt Cài đặt dự án, và chạy Setup check.

Cài đặt cấu hình Android, team ký cho iOS device, AI CLI, Jira, Amplitude và App Store Connect. Đầu mỗi phần ghi khi nào cần dùng phần đó.

Mở Cài đặt bằng Cmd+, hoặc Astra Scout > Cài đặt…. Cửa sổ có thanh bên với các mục: Chung, Android, iOS, AI, Jira, Amplitude và App Store. Mục App Store có tiêu đề App Store Connect.

• Thay đổi có hiệu lực ngay khi chỉnh, trừ chỗ có nút Lưu.
• Nút Quay lại và Tiến tới trên toolbar đi qua các mục đã xem. Trong một trang mở từ một mục, Quay lại về mục đó trước.
• Nút "?" trên toolbar mở phần của trang này ứng với mục. Mục Jira không có nút này.

Chung

1. Mở Cài đặt > Chung.

2. Ở Soạn thảo, bật hoặc tắt Tự động lưu. Nó lưu thay đổi của file sau một khoảng trễ ngắn.

3. Ở Ngôn ngữ, chọn Mặc định hệ thống, English hoặc Tiếng Việt. Có hiệu lực sau khi khởi động lại. Khi chọn ngôn ngữ khác, nút Khởi động lại ngay hiện ra. Bấm nó để thoát và mở lại Astra Scout.

4. Mục Cập nhật chỉ hiện ở bản build có thể tự cập nhật. Nó có Tự động kiểm tra bản cập nhật, Phiên bản đang chạy và Kiểm tra bản cập nhật… (có cả trong menu Astra Scout). Astra Scout kiểm tra mỗi ngày một lần và hỏi trước khi cài bản mới. Xem Cập nhật.

5. Mục Tài khoản (chỉ hiện khi app yêu cầu đăng nhập) cho biết tài khoản Google đang đăng nhập (tên, email, lần xác minh gần nhất). Bấm Đăng xuất… để đăng xuất; dùng lại app cần đăng nhập Google lần nữa.

Astra Scout theo giao diện của macOS (Sáng hoặc Tối) và không có cài đặt giao diện riêng.

Android

Cần khi test trên Android. Astra Scout dùng Android SDK (cài cùng Android Studio) để nói chuyện với emulator và điện thoại Android. Mục Android SDK cho Astra Scout biết SDK ở đâu. App thường tự tìm thấy SDK.

1. Mở Cài đặt > Android.
2. Đọc Đường dẫn và Trạng thái. Đường dẫn cho biết SDK đang dùng. Trạng thái ghi "Đã phát hiện (…)" kèm nơi tìm thấy, "Đặt trong Cài đặt" khi đã chọn đường dẫn, hoặc "Không tìm thấy".
3. Nếu không tìm thấy SDK, hoặc cần dùng SDK khác, gõ đường dẫn vào Đường dẫn tuỳ chỉnh, hoặc bấm Chọn thư mục… rồi chọn thư mục SDK. Để trống Đường dẫn tuỳ chỉnh thì app tự phát hiện.
4. Khi đường dẫn tốt, Đường dẫn hợp lệ hiện ra. Nếu không, một thông báo hỏi đường dẫn có đúng không.
5. Nếu cài SDK khi Cài đặt đang mở, bấm Kiểm tra lại.

Khi đường dẫn tuỳ chỉnh trống, Astra Scout tìm theo thứ tự: biến môi trường ANDROID_HOME, ANDROID_SDK_ROOT, rồi thư mục mặc định ~/Library/Android/sdk.

iOS

Cần khi test trên iOS device; iOS Simulator không cần. Để điều khiển iOS device, Astra Scout phải ký WebDriverAgent (WDA), app nhỏ chạy trong iOS device, bằng một team Apple Developer. Mục Team ký app chọn team đó, nhận diện bằng Team ID, mã 10 ký tự. Mục này cần một Apple ID đã đăng nhập trong Xcode (Xcode > Settings > Accounts) và Developer Mode bật trên iOS device.

1. Mở Cài đặt > iOS.
2. Chọn một hàng:
   • Tự động dùng team duy nhất trong Keychain.
   • Mỗi team Apple Development tìm thấy trong Keychain một hàng, kèm Team ID, chứng chỉ và ngày hết hạn.
3. Để dùng team không có trong danh sách, bấm Team ID khác…, gõ Team ID gồm 10 ký tự (ví dụ ABCDE12345) rồi bấm Lưu. Team ID là mã ở developer.apple.com > Membership details (app đọc nó từ chứng chỉ), không phải mã trong ngoặc ở tên chứng chỉ.
4. Nếu không có team nào, đăng nhập Xcode, tạo chứng chỉ Apple Development rồi bấm Quét lại.
5. Dòng dưới danh sách ghi "Đang dùng: …" kèm nguồn của team: chọn trong Cài đặt, hoặc tự phát hiện vì là team duy nhất trong Keychain. Khi chạy server từ dòng lệnh, --team-id hoặc MAESTRO_TEAM_ID cũng đặt được team.

Bản build mà clearState sử dụng được chọn ở Window > Builds, không phải ở đây. Xem Builds.

AI

Cần khi dùng tính năng AI (chat, Khám phá app, tự sửa, lệnh AI trong flow). AI CLI là công cụ AI chạy trong Terminal (Claude Code, Codex, Gemini CLI); Astra Scout dùng CLI đã cài thay vì có AI riêng. Mục này có ba phần.

• Agent liệt kê các CLI AI tìm thấy trên máy Mac này (Claude Code, Codex, Gemini CLI) kèm trạng thái: Sẵn sàng, Chưa đăng nhập hoặc Chưa cài. Bấm Quét lại sau khi cài hoặc đăng nhập một CLI. Một dòng cho biết có bao nhiêu CLI đã có plugin.
• Mặc định có ba menu: Nhà cung cấp mặc định (Tự động dùng CLI đã đăng nhập đầu tiên), Lệnh AI trong flow (CLI nào chạy assertWithAI, assertNoDefectsWithAI và extractTextWithAI; Mặc định dùng nhà cung cấp mặc định) và Model. Xem Trợ lý AI.
• Astra Scout cho CLI chứa Kết nối MCP và Môi trường shell.

App không nhúng terminal. App hiện đúng lệnh cần chạy, với nút Sao chép và Chạy, và không có gì chạy cho tới khi bấm Chạy.

Thiết lập một CLI

1. Mở Cài đặt > AI và bấm một CLI trong Agent, ví dụ Claude Code.
2. Đặt Model (mặc định của CLI nếu không chọn), Tham số thêm (ví dụ --effort low cho Claude Code) và Đường dẫn CLI (để trống thì tự tìm CLI).
3. Ở mục Plugin, đọc trạng thái của Plugin Astra Scout: Chưa có CLI, CLI chưa đăng nhập, Chưa cài, Cần cập nhật hoặc Đã cài.
4. Bấm Cài đặt (hoặc Cập nhật). Một mục tên "Cài đặt cho Claude Code" hiện ra kèm lệnh.
5. Đọc lệnh rồi bấm Chạy. Một log hiện kết quả, và trạng thái ghi Đang chạy…, Đã xong hoặc mã thoát. Dừng kết thúc nó. Sao chép lệnh để tự chạy.
6. Bấm Kiểm tra lại để đọc lại trạng thái plugin.

Xem Plugin scout.

Kết nối MCP

Kết nối MCP cho phép AI CLI điều khiển Astra Scout, ví dụ chạy flow, qua MCP, một chuẩn để công cụ AI gọi tính năng của app khác. Token là mật khẩu của kết nối đó, để chỉ CLI mới dùng được. Hàng của nó trong mục ghi "Bật · host:port", "Tắt" hoặc "Không khả dụng".

1. Mở Cài đặt > AI > Kết nối MCP.
2. Bật Bật kết nối từ CLI (MCP).
3. Đọc URL và sao chép bằng Sao chép URL. Nếu Astra Scout không dùng cổng mặc định 5050, một warning cho biết điều đó.
4. Token bị che. Dùng Hiện token hoặc Ẩn token, Sao chép token, và Tạo token mới. Tạo token mới sẽ hỏi Tạo lại token MCP?. Xác nhận bằng Tạo token mới. Mọi CLI đang dùng token cũ bị từ chối cho đến khi đặt token mới.
5. Làm theo 1. Đặt token: sao chép dòng export và chạy trong terminal, hoặc thêm vào ~/.zshrc.
6. Làm theo 2. Đăng ký Astra Scout với CLI: chọn CLI trong ô chọn, sao chép lệnh và chạy trong terminal. Lệnh không chứa token.
7. Khi MCP đang bật, Hoạt động từ CLI liệt kê các lệnh gọi mới nhất từ CLI, mỗi lệnh kèm OK, Chờ xác nhận, Quá nhiều lệnh hoặc Error. Mục ghi "Chưa có CLI nào gọi Astra Scout." cho đến khi có lệnh gọi.

Xem Plugin scout.

Môi trường shell

Môi trường shell lưu token (và địa chỉ, khi cần) vào profile shell (file mà Terminal đọc mỗi lần mở, như ~/.zshrc), để CLI tự đọc được. Hai biến đó là SCOUT_MCP_TOKEN và SCOUT_MCP_URL.

1. Mở Cài đặt > AI > Môi trường shell.
2. Bấm Thêm vào profile shell ở hàng SCOUT_MCP_TOKEN. Nút bị vô hiệu khi MCP không khả dụng. Hàng SCOUT_MCP_URL với nút Đặt trong profile shell chỉ hiện khi Astra Scout không dùng cổng 5050.
3. Một mục hiện lệnh và dòng nó thêm vào file profile, thay mọi dòng cũ của cùng biến.
4. Bấm Chạy. Chưa có gì thay đổi cho đến lúc đó.

Jira

Cần khi báo bug lên Jira từ một run. Mục Jira chỉ giữ phần đăng nhập. Dự án, loại issue, nhãn và các mục báo cáo khác nằm trong Cài đặt dự án. Xem Jira.

1. Mở Cài đặt > Jira. Ở Tài khoản, hàng Jira Cloud cho biết đã đăng nhập chưa.
2. Bấm Kết nối. Đăng nhập Jira Cloud trong trình duyệt; hàng ghi "Đang chờ đăng nhập trong trình duyệt…". Huỷ dừng việc chờ.
3. Kết nối bị vô hiệu cho đến khi admin thiết lập App OAuth. App OAuth đăng ký Astra Scout với Atlassian để Jira cho phép đăng nhập. Admin Jira thiết lập cho cả team; tester không phải làm. Admin mở hàng App OAuth, hàng này có URL callback cần đăng ký (kèm Sao chép URL), Client ID và Client secret (gõ rồi bấm Lưu). Mở Hướng dẫn Admin mở trang Jira. Hàng này bị ẩn khi cả hai giá trị đến từ biến môi trường.
4. Khi đã kết nối, bấm Ngắt kết nối để đăng xuất. Nút Cài đặt dự án… mở các mục báo cáo của dự án.

Nếu không đọc được thông tin đăng nhập đã lưu, hàng sẽ báo và yêu cầu kết nối lại.

Amplitude

Cần khi kiểm tra tracking: Astra Scout so sánh event analytics mà app gửi với danh sách event mong đợi. Mục này khai báo project Amplitude (nơi event được lưu) để Astra Scout đọc lại và đối chiếu. Xem Tracking.

Mạng

Công tắc Nhận event từ device trong mạng nằm ở đầu mục, dưới Mạng. Khi app test gửi event analytics, Astra Scout nhận chúng ở cổng 5051, gọi là listener. Công tắc này cho phép các device khác cùng Wi-Fi gửi event tới listener. Công tắc bật sẵn để iOS device hoặc Android device gửi được event mà không cần cài đặt gì. Tắt khi dùng mạng công cộng. Simulator và emulator không cần nó. Có hiệu lực sau khi server khởi động lại: bấm Khởi động lại server ngay khi nút hiện ra.

Thêm một project

1. Mở Cài đặt > Amplitude. Ở Project, bấm Thêm project…. Sheet Project Amplitude mở ra.
2. Gõ Tên, API key và Secret key của project Amplitude mà run được đọc lại từ đó. Project mới cần cả hai key.
3. Để Vùng ở Tự động, hoặc chọn US hay EU.
4. Không bắt buộc: điền ID project Amplitude. Khi Amplitude đã báo ID project cho các run, một nút sẽ đề xuất nó.
5. Không bắt buộc: bật Chuyển tiếp event tới Amplitude. Nó gửi tiếp các event đã bắt tới Amplitude, nên chỉ bật cho Staging. Khi bật, app yêu cầu xác nhận.
6. Không bắt buộc: ở Key của app, gõ một key vào App key mới rồi bấm + (Thêm app key). Dùng khi các bản build app gửi API key khác. Để gỡ một key, chọn hàng của nó rồi bấm − (Gỡ key của app).
7. Bấm Lưu.

Cả hai key được lưu mã hoá trên máy Mac này và không bao giờ hiện lại. Khi sửa một project, để trống Secret key để giữ nguyên.

Vùng Tự động

Khi Vùng ở Tự động, Astra Scout thử vùng US trước, rồi EU, và giữ vùng mà key dùng được. Việc này xảy ra khi kiểm tra kết nối. Sau khi lưu project mới, hoặc đổi key hay vùng của nó, Astra Scout tự chạy phép kiểm tra đó. Kiểm tra kết nối chạy lại phép kiểm tra. Kết quả ghi Đã kết nối · US hoặc Đã kết nối · EU, hoặc một thông báo fail. Khi chưa tìm được vùng, các yêu cầu đi tới US.

Quản lý một project

Mỗi project trong danh sách hiện tên, vùng và bốn ký tự cuối của các key. Nó có:

• Chuyển tiếp event tới Amplitude (một công tắc).
• Kiểm tra kết nối.
• Sửa…, mở sheet với tên Sửa project Amplitude.
• Nút thùng rác (Xoá project). App hỏi trước, rồi gỡ project và các key của nó khỏi máy Mac này.

Mục ghi "Cần nhập lại key Amplitude" khi các key đã lưu không mở được nữa. Thêm lại các project. Xem Tracking.

App Store

Cần khi test mua hàng. Sandbox tester là tài khoản Apple dành riêng để mua thử mà không mất tiền. Mục này có tiêu đề App Store Connect. Nó cho Astra Scout đổi tốc độ gia hạn gói đăng ký của sandbox tester và xoá lịch sử mua của tester, thông qua một API key tạo trong App Store Connect. Xem Sandbox tester.

Thêm API key

1. Trong App Store Connect, mở Users and Access > Integrations và tạo một key với vai trò Admin. Tải file .p8 về.
2. Trong Astra Scout, mở Cài đặt > App Store. Ở API key, gõ Issuer ID và Key ID. Với key cá nhân, bật Individual key (không có Issuer ID) và ô Issuer ID biến mất.
3. Bấm Chọn file .p8… và chọn file. Hàng ghi "Đã chọn key: … Bấm Lưu."
4. Bấm Lưu. Hàng khi đó ghi Đã lưu key.
5. Bấm Kiểm tra kết nối. Kết quả ghi "Đã kết nối" kèm số sandbox tester.

File .p8 được lưu mã hoá trên máy Mac này và không bao giờ hiện lại. Gỡ xoá key khỏi máy này sau khi xác nhận. Nếu không mở được key đã lưu nữa, chọn lại file .p8.

Chọn sandbox tester

1. Khi đã lưu key, mục Sandbox tester hiện ra. Chọn một tester ở Sandbox tester. Nếu danh sách trống, tạo một tester trong App Store Connect ở Users and Access > Sandbox.
2. Chọn Tốc độ gia hạn gói đăng ký: mỗi 3 phút, mỗi 5 phút (mặc định của Apple), mỗi 15 phút, mỗi 30 phút hoặc mỗi giờ. Một dòng bên dưới cho biết gói 6 tháng kéo dài bao lâu ở tốc độ đó.
3. Apple có thể mất tới một giờ để áp dụng tốc độ gia hạn mới.

Cài đặt dự án

Cài đặt dự án cho team dùng chung một workspace cùng nơi nhận báo cáo bug và cùng mô tả về app. Chúng thuộc về workspace đang mở, không thuộc về app. Cửa sổ được lưu cùng workspace (trong thư mục .scout), nên ai mở dự án cũng dùng chung. Thay đổi có hiệu lực ngay, trừ Ngữ cảnh app có nút Lưu.

1. Mở một workspace.
2. Chọn File > Cài đặt dự án… (Option+Cmd+,). Khi chưa có workspace, cửa sổ ghi "Hãy mở một workspace để đổi cài đặt của nó."

Cửa sổ có các mục sau:

• Nơi nhận báo cáo (Jira): Site (khi có nhiều hơn một), Dự án, Loại issue, Nhãn mặc định, Components, Ngôn ngữ bug, và Đặt Priority theo severity (mức 5 là priority cao nhất của dự án, 1 là thấp nhất). Đăng nhập Atlassian vẫn nằm ở Cài đặt > Jira. Nếu chưa kết nối Jira, mục này hiện Kết nối Jira trong Cài đặt….
• Crash, hiện khi đã kết nối Jira và đã chọn dự án: Tự gửi crash tạo issue Jira khi app crash, trừ khi đã có issue trùng. Số issue tối đa mỗi giờ từ 1 đến 20 (mặc định 3). Chỉ đổi được khi đang tắt tự gửi, và tự gửi tắt lại sau khi khởi động lại. Xem Jira.
• Ngữ cảnh app: mô tả app bằng lời để AI hiểu đúng, gồm tên màn hình, tên gói và thuật ngữ của app, tối đa 16 KiB. Một bộ đếm ghi "N KB of 16 KB" (N là dung lượng đã gõ). Gõ văn bản rồi bấm Lưu. AI đọc nó ở mỗi lần gọi. Xem Trợ lý AI.

Kiểm tra thiết lập

Help > Kiểm tra thiết lập… mở một sheet tên Kiểm tra thiết lập kiểm tra máy và chỉ cách khắc phục từng mục. Các phép kiểm tra chỉ đọc và không thay đổi gì.

1. Chọn Help > Kiểm tra thiết lập…. Sheet được điền dần khi các phép kiểm tra xong.
2. Đọc phần tóm tắt: các số "N pass", "N warning" và "N fail" kèm biểu tượng.
3. Đọc từng nhóm. Hàng chưa OK giải thích issue và cách sửa, và ghi "(bắt buộc)" nếu là mục bắt buộc. Một số hàng có nút mở đúng mục trong Cài đặt hoặc mở hướng dẫn.
4. Sửa một mục rồi bấm Kiểm tra lại.
5. Bấm Tài liệu để mở tài liệu. Bấm Xong để đóng sheet.

Nhóm	Kiểm tra gì
Xcode	Xcode có mặt và xcode-select trỏ tới nó, phiên bản, license và lần mở đầu, Command Line Tools, và runtime iOS cho simctl. Các mục này là bắt buộc.
iOS signing	Chứng chỉ Apple Development trong Keychain, Team ID đang dùng, và warning với Personal Team (profile 7 ngày).
iOS device	Với mỗi iOS device đang cắm: tin cậy Mac, Developer Mode, đang khoá hay mở khoá, Developer Disk Image, nhắc về Auto-Lock, và Direct iOS device control (HID).
Mirror & video	Hai công cụ phụ trợ, đều không bắt buộc: xcuiax (đọc cây phần tử của simulator nhanh hơn) và ffmpeg (chỉ dùng để cắt đoạn video trong báo cáo bug).
Android	SDK và adb, một AVD, và USB debugging đã được cho phép trên device.
AI	Đã cài CLI và đã đăng nhập.
Quyền macOS	Local Network (iOS device qua Wi-Fi).

App cũng chạy kiểm tra này ở nền ngay lần đầu mở app. Nếu thiếu mục bắt buộc, nó mở sheet với "Máy này chưa thiết lập đủ để chạy flow".