Kết nối Apple Search Ads với Claude hoặc ChatGPT trong năm phút

Trình kết nối Apple Search Ads của Hermoso liên kết tài khoản Apple Ads của bạn với Claude, ChatGPT, Cursor, CLI hoặc HTTP thuần, để một agent có thể chạy quảng cáo tìm kiếm trên App Store cho bạn. Nó tạo chiến dịch, nhóm quảng cáo, từ khóa nhắm mục tiêu và từ khóa phủ định, đọc lại những gì Apple thực sự lưu, và báo cáo hiệu quả đến từng cụm từ tìm kiếm mà ai đó đã gõ trước khi cài ứng dụng. Mọi thứ nó tạo ra đều ở trạng thái tạm dừng, và việc bật chi tiêu là một bước riêng, phải được xác nhận rõ ràng. Báo cáo có thể đổ vào Google Sheet, dashboard Looker Studio hoặc file JSON, và trang Apple Ads MCP liệt kê mọi thứ trình kết nối làm được.

Kết nối mất khoảng năm phút. Bạn sẽ không phải chạy openssl, và không mật khẩu Apple nào đi qua Hermoso.

Kết nối Apple Search Ads với Claude

Để kết nối Apple Search Ads với Claude, hãy thêm Hermoso vào Claude như một connector, rồi kết nối tài khoản Apple Ads bên trong Hermoso một lần. Trong Claude, mở Customize › Connectors › Add custom connector, đặt tên là Hermoso, dán https://app.hermoso.ai/mcp và phê duyệt bằng tài khoản Hermoso của bạn. Không có key nào cần dán vào Claude. Sau đó kết nối Apple Ads trong Hermoso tại Cài đặt › Trình kết nối, theo các bước ở phần bên dưới trang này. Từ lúc đó Claude có thể gọi mọi công cụ Apple Ads mà Hermoso có: hỏi báo cáo, thay đổi từ khóa hay tạo chiến dịch mới bằng lời thường. Trong Claude Code, thay vào đó bạn chỉ cần hai lệnh: /plugin marketplace add hermoso-ai/hermoso, rồi /plugin install hermoso@hermoso. Hermoso trong Claude có đầy đủ các bước.

Kết nối Apple Search Ads với ChatGPT

ChatGPT hoạt động theo cùng cách. Trong ChatGPT, mở Plugins, rồi Add › Create MCP App, đặt tên là Hermoso, dán https://app.hermoso.ai/mcp làm Server URL, giữ Authentication ở OAuth và phê duyệt bằng tài khoản Hermoso của bạn. Nếu không thấy Create MCP App, hãy bật Developer mode một lần trong Cài đặt › Plugins › Developer mode. Khi Apple Ads đã kết nối trong Hermoso, ChatGPT có thể lấy báo cáo từ khóa của bạn, ghi vào Google Sheet hoặc soạn một chiến dịch để bạn kiểm tra. Hermoso trong ChatGPT có hướng dẫn từng bước.

Cursor, Codex và mọi client MCP khác

Mọi client dùng giao thức Model Context Protocol đều truy cập được cùng công cụ tại cùng địa chỉ. Cursor đọc https://app.hermoso.ai/mcp từ file mcp.json của nó; Codex dùng plugin Hermoso qua codex plugin marketplace add hermoso-ai/hermoso, chạy cùng công cụ đó từ terminal. Dù bạn dùng client nào, thông tin đăng nhập Apple của bạn cũng không đi qua khung chat. Agent gọi công cụ của Hermoso, và Hermoso ký từng yêu cầu gửi tới Apple bằng key mà nó giữ. Trang Apple Ads MCP liệt kê mọi công cụ.

Những gì nên hỏi sau khi đã kết nối

• “Lấy báo cáo hiệu quả Apple Search Ads tuần trước theo từ khóa, và cho tôi xem mười từ khóa có chi phí mỗi lượt cài đặt (CPA) cao nhất.”
• “Đưa chi tiêu, lượt cài đặt và CPA của 30 ngày gần nhất theo chiến dịch vào một Google Sheet mới tên Apple Ads.” (Hãy kết nối Google Drive trước.)
• “Những cụm từ tìm kiếm nào đã mang lại lượt cài đặt trong chiến dịch Mỹ của tôi tháng này mà tôi chưa đặt giá thầu làm từ khóa chính xác?”
• “Thêm ‘budget planner’ và ‘expense tracker’ làm từ khóa khớp chính xác trong nhóm quảng cáo Brand, và ‘jobs’ làm từ khóa phủ định.”
• “Apple gợi ý từ khóa nào cho ứng dụng của tôi, và tôi đang chiếm bao nhiêu phần trăm lượt hiển thị trên những từ khóa đã đặt giá thầu?”
• “Tạo một chiến dịch đang tạm dừng cho ứng dụng của tôi tại Vương quốc Anh với ngân sách 50 đô la mỗi ngày, rồi cho tôi xem Apple đã lưu những gì.”

Đọc báo cáo không bao giờ chạm đến chi tiêu. Bất cứ thứ gì agent tạo đều ở trạng thái tạm dừng, và công tắc bật chi tiêu chờ sự xác nhận rõ ràng của bạn.

Trước hết, điều khiến hầu hết mọi người bế tắc

Hướng dẫn của chính Apple viết: “Trong Ads UI, chọn Account Settings › API. Dán key vào trường Public Key.”

Trường đó không tồn tại đối với Account Admin. Đăng nhập với vai trò admin trên tài khoản của bạn, mở Account Settings › API, và thứ hiện ra là một bảng có tiêu đề Manage API Access (danh sách các nhà cung cấp dịch vụ bên thứ ba, với một thao tác duy nhất là Remove Access) và không có trường key nào trên trang. Nhìn vào thì nó giống hệt một tính năng chưa có, nên người ta dừng lại ở đó và kết luận rằng API không dành cho họ.

Thực ra họ vẫn dùng được. Trường Public Key thuộc về người dùng có vai trò API, và việc là admin của tài khoản thì không phải là vai trò đó. Hộp thoại mời của Apple đưa ra sáu vai trò, trong đó chỉ có đúng hai vai trò API:

• API Account Manager: “quyền đọc và ghi trên tất cả nhóm chiến dịch để quản lý API”. Đây là vai trò nên chọn nếu bạn muốn Hermoso tạo chiến dịch, không chỉ báo cáo.
• API Account Read Only: “quyền chỉ đọc trên tất cả nhóm chiến dịch để quản lý API”. Đủ cho báo cáo, và không làm được gì khác.

Bốn vai trò còn lại (Account Admin, Account Finance, Account Read Only và Limited Access) hoàn toàn không tạo được thông tin xác thực API. Vì vậy cách sửa là gửi một lời mời cho chính bạn:

1. Mở Account Settings › User Management và chọn Invite Users.
2. Mời một địa chỉ mà bạn kiểm soát (địa chỉ của bạn, hoặc một địa chỉ dùng chung như ads-api@yourcompany.com để thông tin xác thực không phụ thuộc vào một người duy nhất) với vai trò API Account Manager.
3. Chấp nhận lời mời từ hộp thư đó, rồi đăng nhập Apple Ads bằng tài khoản người dùng đó.

Lúc này Account Settings › API đã có trường Public Key.

Kết nối, từng bước

1. Bắt đầu trong Hermoso. Cài đặt › Trình kết nối › Apple Ads › Connect. Hermoso tạo một khóa ký EC P-256 (cùng loại khóa prime256v1 mà hai lệnh openssl của Apple sẽ tạo ra) và chỉ hiển thị nửa công khai. Hãy sao chép nó.
2. Đưa nửa công khai cho Apple. Với tư cách người dùng có vai trò API, mở Account Settings › API, dán vào Public Key và nhấn Save.
3. Sao chép ba mã trở lại. Lúc này Apple hiển thị clientId, teamId và keyId phía trên trường đó. Cả ba.
4. Hoàn tất trong Hermoso. Dán ba mã và lưu. Hermoso đổi token với Apple và đọc danh sách tổ chức của bạn trước khi lưu bất cứ thứ gì, nên mã gõ sai sẽ báo lỗi ngay tại đó, khi bạn vẫn còn thấy đúng những gì mình đã dán, chứ không phải một giờ sau khi báo cáo đầu tiên lỗi.
5. Chọn tổ chức, nếu thông tin xác thực của bạn bao phủ nhiều hơn một tổ chức. Kết nối được gắn cố định vào tổ chức bạn chọn.

Nếu có lỗi

Không có trường Public Key trên trang API

Bạn đang đăng nhập với vai trò Account Admin, hoặc với bất kỳ vai trò không phải API nào trong bốn vai trò kia. Hãy mời chính mình làm API Account Manager và đăng nhập bằng tài khoản đó (xem phần trên). Đây là lý do phổ biến nhất khiến một kết nối Apple Ads không bao giờ được tạo.

Apple từ chối thông tin xác thực

Ba mã phải thuộc về key mà Apple đang giữ. Hãy sao chép lại clientId, teamId và keyId từ ngay phía trên trường Public Key, không lấy từ một key cũ bạn đã thay thế. Nếu vẫn lỗi, hãy bắt đầu lại kết nối trong Hermoso: thao tác này tạo một cặp khóa mới, và bạn dán nửa công khai mới vào Apple.

Phiên thiết lập đã hết hạn

Hermoso giữ khóa riêng đã tạo trong 24 giờ, trong lúc bạn đi dán nửa công khai vào Apple. Sau thời gian đó khóa bị xóa, và đây là có chủ đích. Hãy bắt đầu kết nối lại và dán public key mới.

Tôi đã tạo key bằng openssl rồi

Vậy thì dùng nó. Khi kết nối, hãy dán khóa riêng EC P-256 hiện có của bạn thay vì dùng khóa của Hermoso, và public key đang nằm trong tài khoản Apple của bạn sẽ tiếp tục hoạt động. Khóa phải là EC P-256 (prime256v1). Apple không chấp nhận đường cong nào khác.

Tôi quản lý nhiều tổ chức Apple Ads

Hãy kết nối từng tổ chức trong một hồ sơ Hermoso riêng. Mỗi kết nối được gắn vào một tổ chức duy nhất, và chính điều đó ngăn chiến dịch của một agency bị đưa nhầm vào tài khoản của khách hàng khác.

Trình kết nối Apple Search Ads làm được gì

Tạo: create_apple_ads_campaign, create_apple_ads_ad_group, add_apple_ads_keywords, add_apple_ads_negative_keywords, update_apple_ads_object, set_apple_ads_status, delete_apple_ads_object.

Đọc: list_apple_ads_campaigns (trạng thái, tình trạng phân phối, ngân sách ngày và tổng, các quốc gia chiến dịch chạy, và lý do Apple tự nêu khi chiến dịch không thể chạy), list_apple_ads_ad_groups (giá thầu mặc định và việc Search Match của Apple có bật hay không), list_apple_ads_keywords (từ khóa nhắm mục tiêu và phủ định, kèm kiểu khớp và giá thầu), apple_ads_report (lượt hiển thị, lượt chạm, lượt cài đặt, chi tiêu, TTR, CPT và CPA ở cấp chiến dịch, nhóm quảng cáo, từ khóa, cụm từ tìm kiếm hoặc quảng cáo) và list_apple_ads_orgs.

Tất cả đều gọi được từ Claude, Claude Code, Codex, Cursor, Cline, OpenClaw, Hermes hoặc bất kỳ client MCP nào khác, và từ studio web. Dù dùng cách nào thì cũng là cùng một engine. Xem tổng quan MCP hoặc tài liệu tham chiếu quảng cáo.

Và nhiều hơn thế: nó tạo creative và quảng cáo (create_apple_ads_creative, create_apple_ads_ad), nạp tối đa 1.000 từ khóa trong một lần gọi (bulk_apple_ads_keywords), và đọc dữ liệu riêng của Apple: apple_ads_keyword_suggestions, apple_ads_impression_share, apple_ads_search_term_popularity và apple_ads_change_history. Mỗi công cụ trong số đó đều gọi được từ cùng một khung chat.

Xuất dữ liệu từ Apple Search Ads

Cùng kết nối đó cũng dùng để báo cáo. apple_ads_report lấy hiệu quả của chiến dịch, nhóm quảng cáo, quảng cáo, từ khóa và cụm từ tìm kiếm (lượt hiển thị, lượt chạm, lượt cài đặt, chi tiêu, tỷ lệ nhấp, chi phí mỗi lượt chạm và chi phí mỗi lượt cài đặt), dưới dạng tổng hoặc chuỗi theo giờ, ngày, tuần hoặc tháng, tối đa 5.000 dòng mỗi trang. Đọc báo cáo không bao giờ chạm đến chi tiêu. Dữ liệu sẽ đi đâu tiếp theo là tùy bạn, và ba nơi phổ biến nhất nằm bên dưới. Hướng dẫn đầy đủ là Xuất dữ liệu từ Apple Search Ads.

Kết nối Apple Search Ads với Google Sheets

Tiếp theo, hãy kết nối Google Drive cùng với Apple Ads (một lần cấp quyền Google bao gồm Drive, Sheets và Docs), rồi yêu cầu agent đưa báo cáo vào một sheet. Nó gọi apple_ads_report, rồi create_sheet để tạo bảng tính mới hoặc append_to_sheet để thêm dữ liệu tuần này vào bảng có sẵn. Hermoso dùng phạm vi drive.file của Google, nên nó chỉ truy cập được các file mà chính nó tạo hoặc bạn đã chọn. Từng bước: Kết nối Apple Search Ads với Google Sheets.

Xuất Apple Search Ads sang Looker Studio

Hermoso không có connector Looker Studio gốc. Looker Studio đọc Google Sheets bằng connector riêng của nó, nên sheet ở trên chính là cầu nối: thêm nó làm nguồn dữ liệu một lần, xây dashboard, và mỗi lần thêm dòng hàng tuần sẽ hiện trên lần làm mới tiếp theo. Power BI và Tableau đọc cùng sheet đó theo cách tương tự. Các bước Looker Studio.

Xuất Apple Search Ads sang JSON

Để lấy dòng dữ liệu thô, hãy gọi công cụ qua REST API của Hermoso bằng một API key: POST https://app.hermoso.ai/v1/tools/apple_ads_report, với các tham số báo cáo làm thân JSON, và đọc các dòng từ data.rows trong phản hồi. Từ terminal, npx -y hermoso call apple_ads_report --json '{...}' --structured in ra cùng kết quả dưới dạng JSON. Một ví dụ yêu cầu đầy đủ.

Câu hỏi thường gặp

Làm thế nào để kết nối Apple Search Ads với Claude?

Thêm Hermoso vào Claude như một custom connector với địa chỉ https://app.hermoso.ai/mcp và phê duyệt bằng tài khoản Hermoso của bạn, rồi kết nối Apple Ads trong Hermoso tại Cài đặt › Trình kết nối. Sau đó Claude có thể báo cáo, chỉnh sửa và tạo chiến dịch Apple Search Ads của bạn qua các công cụ Apple Ads của Hermoso.

ChatGPT có đọc được dữ liệu Apple Search Ads của tôi không?

Có. Thêm https://app.hermoso.ai/mcp trong ChatGPT tại Plugins › Add › Create MCP App, rồi kết nối Apple Ads trong Hermoso. Sau đó ChatGPT có thể lấy lượt hiển thị, lượt chạm, lượt cài đặt, chi tiêu, TTR, CPT và CPA theo chiến dịch, nhóm quảng cáo, quảng cáo, từ khóa hoặc cụm từ tìm kiếm, rồi ghi các dòng đó vào Google Sheet.

Có máy chủ MCP cho Apple Search Ads không?

Có. Máy chủ MCP được lưu trữ của Hermoso tại https://app.hermoso.ai/mcp cung cấp toàn bộ bộ công cụ Apple Ads cho Claude, ChatGPT, Cursor, Codex hoặc bất kỳ client MCP nào: báo cáo, chiến dịch, nhóm quảng cáo, từ khóa và từ khóa phủ định, creative và quảng cáo, cùng các gợi ý từ khóa của Apple. Mọi thứ nó tạo ra đều ở trạng thái tạm dừng.

Tại sao trang API của Apple Ads không có trường Public Key?

Vì bạn đang đăng nhập với vai trò Account Admin. Apple chỉ hiển thị trường đó cho người dùng có vai trò API. Admin sẽ thấy thay vào đó một bảng “Manage API Access” liệt kê các nhà cung cấp dịch vụ bên thứ ba, và không có trường key nào trên trang. Hãy mời chính bạn làm API Account Manager trong Account Settings › User Management, đăng nhập bằng tài khoản đó, và trường sẽ hiện ra.

Tôi cần vai trò Apple Ads nào?

API Account Manager nếu bạn muốn Hermoso tạo chiến dịch, nhóm quảng cáo và từ khóa. Apple mô tả vai trò này là “quyền đọc và ghi trên tất cả nhóm chiến dịch để quản lý API”. API Account Read Only là đủ nếu bạn chỉ cần báo cáo. Bốn vai trò còn lại mà Apple đưa ra (Account Admin, Account Finance, Account Read Only và Limited Access) hoàn toàn không tạo được thông tin xác thực API.

Tôi có phải chạy openssl không?

Không. Hướng dẫn của Apple đưa cho bạn hai lệnh openssl; Hermoso tự tạo cặp khóa EC P-256 cho bạn và chỉ hiển thị nửa công khai. Nửa riêng là thứ ký các yêu cầu của bạn, và bạn không bao giờ thấy, dán hay lưu nó. Nếu bạn đã có khóa từ công cụ khác, bạn có thể mang khóa đó vào.

Kết nối Apple Ads có tốn phí hay rủi ro chi tiêu không?

Không. Các thao tác đọc gọi thoải mái, và mọi đối tượng Hermoso tạo ra đều được tạo ở trạng thái TẠM DỪNG, không có ngoại lệ. Bật một đối tượng là công tắc duy nhất kích hoạt chi tiêu thật, và nó cần xác nhận rõ ràng.

clientId, teamId và keyId là gì?

Ba mã định danh mà Apple hiển thị phía trên trường Public Key sau khi bạn lưu key. Chúng nhận diện người dùng API của bạn với Apple; khóa riêng chứng minh đó là bạn. Dán cả ba trở lại Hermoso là xong kết nối.

Một kết nối có thể bao phủ nhiều tổ chức Apple Ads không?

Một kết nối được gắn vào đúng tổ chức bạn chọn khi tạo nó. Apple coi orgId gần giống một nhóm chiến dịch, nên một lần đăng nhập có thể bao phủ nhiều tổ chức. Một agency có mỗi khách hàng một tổ chức thì kết nối từng tổ chức trong hồ sơ Hermoso riêng.

Tôi có phải thay key mỗi 180 ngày không?

Không. Apple giới hạn client secret ở 180 ngày, đó là lý do hướng dẫn của Apple yêu cầu bạn ghi nhớ việc thay mới. Hermoso giữ khóa riêng và tạo một secret mới, có thời hạn ngắn, cho mỗi lần đổi token, nên không có gì nằm trong file cấu hình để hết hạn.

Tôi có thể xuất dữ liệu Apple Search Ads sang Google Sheets hoặc Looker Studio không?

Có. Kết nối Google Drive cùng với Apple Ads, rồi agent của bạn ghi báo cáo vào một Google Sheet bằng create_sheet hoặc append_to_sheet. Hermoso không có connector Looker Studio gốc; Looker Studio đọc sheet đó bằng connector Google Sheets riêng của nó.

Tôi có thể lấy dữ liệu Apple Search Ads dưới dạng JSON không?

Có. Gọi POST /v1/tools/apple_ads_report trên API của Hermoso bằng một API key và đọc data.rows, hoặc chạy hermoso call apple_ads_report với --structured từ CLI.