Tài liệu này dành cho người dùng AiLogin để thiết kế kịch bản tự động hóa (Workflow), tra cứu toàn bộ 65+ khối lệnh (Blocks), sử dụng hệ thống Biến động & Bảng dữ liệu, cũng như kết nối kịch bản với các dịch vụ API / Webhook bên ngoài.

1. Tổng Quan Cách Hoạt Động Của Kịch Bản (Workflow)#

Mỗi kịch bản tự động hóa trong AiLogin được xây dựng dưới dạng lưu đồ gồm các Khối lệnh (Nodes) và các Đường nối (Edges) quyết định thứ tự thực thi.

1.1. Các Cổng Kết Nối (Output Ports / Handles)#

Một khối lệnh có thể có một hoặc nhiều cổng đầu ra để điều hướng luồng chạy:

• Luồng chính (default): Chạy bước tiếp theo sau khi khối lệnh hiện tại hoàn tất (hoặc sau khi vòng lặp đã chạy hết số lần quy định).
• Nhánh Đúng / Sai (true / false): Dùng cho các khối kiểm tra như Element exists hoặc If / Else.
• Nhánh Điều kiện (path_1, path_2, ... & fallback): Dùng cho khối Conditions. Hệ thống kiểm tra từ trên xuống dưới, nhánh nào thỏa mãn đầu tiên sẽ được chạy; nếu không nhánh nào đúng sẽ đi theo cổng fallback.
• Thân Vòng lặp (loop): Dùng cho các khối Loop, Loop data, Loop elements, While loop. Các khối nối từ cổng loop sẽ được lặp đi lặp lại; khi kết thúc vòng lặp, kịch bản đi tiếp qua cổng default.
• Nhánh Bắt lỗi (fallback trên khối lệnh thường): Nếu một thao tác (ví dụ: Click hoặc Chờ phần tử) gặp lỗi và bạn nối cổng fallback của khối đó sang một nhánh xử lý khác (như Chụp màn hình lỗi hoặc Tải lại trang), kịch bản sẽ tự động chạy nhánh fallback rồi tiếp tục thay vì dừng đột ngột.

1.2. Tùy Chọn Chung Trên Mỗi Khối Lệnh (settings)#

• Bật / Tắt khối lệnh (enabled): Khi tắt (false), kịch bản sẽ bỏ qua khối lệnh đó và đi thẳng sang khối kế tiếp.
• Tiếp tục khi lỗi (continueOnError): Khi bật (true), nếu khối lệnh gặp lỗi (ví dụ không tìm thấy phần tử), kịch bản vẫn tiếp tục chạy bước tiếp theo mà không báo thất bại.

2. Hệ Thống Biến Số & Bảng Dữ Liệu (Variables & Data Tables)#

Bạn có thể chèn giá trị của bất kỳ biến nào vào các ô nhập liệu (URL, Selector, Văn bản gõ, Nội dung API, Đường dẫn file...) bằng cú pháp {{ten_bien}}.

2.1. Quy Tắc Nội Suy Biến#

• Chèn biến vào chuỗi: Ví dụ https://example.com/user/{{username}}/page/{{loop.iteration}}.
• Truyền trực tiếp mảng / đối tượng: Trong các khối xử lý dữ liệu (split_data, sort_data, regex_variable), bạn có thể nhập trực tiếp tên biến (ví dụ myList) hoặc dùng {{myList}}.
• Nếu tên biến chưa được khởi tạo, chuỗi {{ten_bien}} sẽ được giữ nguyên để giúp bạn dễ dàng nhận biết tên biến bị gõ sai.

2.2. Danh Sách Biến Hệ Thống Có Sẵn (Built-in Variables)#

3. Cách Viết Selector (CSS / XPath) & Làm Việc Với Iframe#

3.1. Tự Động Nhận Diện CSS Selector và XPath#

Tất cả các ô nhập Selector trong AiLogin đều hỗ trợ cả CSS Selector lẫn XPath mà không cần chuyển đổi chế độ thủ công:

• XPath: Khi chuỗi bắt đầu bằng dấu / hoặc (:
• Ví dụ 1: //button[contains(text(), "Đăng nhập")]
• Ví dụ 2: (//div[@class="product-card"])[1]//a
• CSS Selector: Tất cả các chuỗi còn lại:
• Ví dụ 1: input[name="email"]
• Ví dụ 2: #login-form > button.btn-primary

3.2. Tương Tác Với Phần Tử Nằm Trong <iframe>#

Mặc định các khối lệnh tìm kiếm phần tử trên trang chính. Nếu phần tử nằm bên trong một khung nhúng <iframe> (ví dụ khung thanh toán, khung captcha, trình soạn thảo):

1. Dùng khối Switch frame (switch_to) với chế độ iframe và nhập Selector của thẻ <iframe>.
2. Thực hiện các khối lệnh Click, Type text, Extract text... như bình thường.
3. Dùng lại khối Switch frame (switch_to) với chế độ main để quay về trang chính (hoặc parent để lùi ra 1 cấp khung nhúng).

4. Tra Cứu Chi Tiết 65+ Khối Lệnh (Workflow Blocks)#

Nhóm A: Điều Khiển Luồng & Kịch Bản Con (Control & Sub-Workflows)#

Nhóm B: Điều Kiện Rẽ Nhánh & Vòng Lặp (Conditions & Loops)#

Bảng 22 Toán Tử Điều Kiện (conditionOperator)#

• So sánh văn bản: equals (bằng tuyệt đối), equals_ci (bằng không phân biệt hoa/thường), not_equals (khác), not_equals_ci, contains (chứa chuỗi), contains_ci, not_contains (không chứa), not_contains_ci, starts_with (bắt đầu bằng), ends_with (kết thúc bằng), regex_match (khớp biểu thức chính quy RegExp).
• So sánh số học: greater_than (>), greater_equal (>=), less_than (<), less_equal (<=).
• Kiểm tra dữ liệu: exists (có giá trị / khác rỗng), not_exists (trống), is_truthy (khác false, 0, null, undefined, no), is_falsy.
• Kiểm tra phần tử trên trang web (vế trái nhập CSS hoặc XPath Selector):
• element_exists: Phần tử có tồn tại trong cây HTML.
• element_not_exists: Phần tử không tồn tại.
• element_visible: Phần tử đang hiển thị rõ trên màn hình (có kích thước > 0 và không bị ẩn).
• element_hidden: Phần tử đang bị ẩn hoặc không tồn tại.

Nhóm C: Điều Hướng Trình Duyệt, Quản Lý Tab, Cửa Sổ & Khung Nhúng#

Nhóm D: Tương Tác Chuột, Bàn Phím & Chờ Đợi (Interaction & Waiting)#

Nhóm E: Trích Xuất Dữ Liệu Trang Web & Chụp Màn Hình (Extraction & Evaluation)#

Nhóm F: Biến Số, Xử Lý Chuỗi/Mảng & Sinh Dữ Liệu Ngẫu Nhiên#

Nhóm G: Bảng Dữ Liệu & Đọc/Ghi Tập Tin (CSV, Excel, JSON, Text)#

Nhóm H: Tích Hợp API Bên Ngoài, Webhook & Đổi Proxy Động (Network & Proxy)#

Nhóm I: Trí Tuệ Nhân Tạo (AI) & Lệnh Hệ Thống#

5. Cấu Trúc File Kịch Bản (.ailogin / JSON) & Ví Dụ Mẫu#

Bạn có thể xuất kịch bản ra file .ailogin (định dạng JSON chuẩn) để chia sẻ, sao lưu hoặc tự sinh kịch bản hàng loạt bằng công cụ bên ngoài rồi nhập (Import) vào AiLogin.

5.1. Cấu Trúc JSON Chuẩn Của Một Kịch Bản#

{
  "name": "Đăng nhập & Lấy mã OTP qua API",
  "description": "Kịch bản mẫu kết hợp kiểm tra phần tử, gọi API lấy OTP và gửi kết quả về Webhook",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "data": {}
    },
    {
      "id": "open_login",
      "type": "open_url",
      "data": {
        "url": "https://example.com/login",
        "openNewTab": false,
        "waitLoad": true
      }
    },
    {
      "id": "check_email_box",
      "type": "element_exists",
      "data": {
        "selector": "input[name='email']",
        "timeoutMs": 5000,
        "visibleOnly": true
      }
    },
    {
      "id": "type_email",
      "type": "type",
      "data": {
        "selector": "input[name='email']",
        "value": "{{row.email}}",
        "clearBefore": true,
        "typingDelay": "40"
      }
    },
    {
      "id": "type_pass",
      "type": "type",
      "data": {
        "selector": "input[name='password']",
        "value": "{{row.password}}",
        "clearBefore": true,
        "typingDelay": "40"
      }
    },
    {
      "id": "click_login",
      "type": "click",
      "data": {
        "targetMode": "element",
        "selector": "button[type='submit']",
        "clickType": "left",
        "humanClick": true
      }
    },
    {
      "id": "fetch_otp_api",
      "type": "api_request",
      "data": {
        "url": "https://api.my-otp-service.example/code?email={{row.email}}",
        "value": "GET",
        "outputKey": "otpData"
      }
    },
    {
      "id": "notify_webhook",
      "type": "webhook",
      "data": {
        "url": "https://hooks.example.com/workflow-done",
        "script": "{\"profile\": \"{{profile.name}}\", \"email\": \"{{row.email}}\", \"status\": \"success\"}"
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "data": {}
    }
  ],
  "edges": [
    { "from": "start_1", "to": "open_login", "sourceHandle": "default" },
    { "from": "open_login", "to": "check_email_box", "sourceHandle": "default" },
    { "from": "check_email_box", "to": "type_email", "sourceHandle": "true" },
    { "from": "check_email_box", "to": "notify_webhook", "sourceHandle": "false" },
    { "from": "type_email", "to": "type_pass", "sourceHandle": "default" },
    { "from": "type_pass", "to": "click_login", "sourceHandle": "default" },
    { "from": "click_login", "to": "fetch_otp_api", "sourceHandle": "default" },
    { "from": "fetch_otp_api", "to": "notify_webhook", "sourceHandle": "default" },
    { "from": "notify_webhook", "to": "end_1", "sourceHandle": "default" }
  ]
}

5.2. Mẹo Kết Hợp API Request & Browser Request Hiệu Quả#

1. Khi nào dùng api_request?

• Khi bạn cần gọi tới dịch vụ bên thứ 3 độc lập với trang web đang mở (ví dụ: dịch vụ giải Captcha 2Captcha/CapMonster/AntiCaptcha, dịch vụ thuê SIM OTP, đọc mail qua API, hoặc đẩy dữ liệu về Google Sheets / Telegram).

1. Khi nào dùng browser_request?

• Khi bạn muốn gọi trực tiếp API nội bộ của chính trang web đang mở trong trình duyệt (tận dụng luôn Cookie và phiên đăng nhập sẵn có của hồ sơ mà không cần tự lấy token).
• Điền thêm trường dataPath (ví dụ data.items.0.id) để lấy thẳng giá trị cần thiết vào biến mà không cần viết thêm bước tách JSON.