通过 Plai 管理 Meta 广告

通过 Plai API 管理 Meta（Facebook 与 Instagram）广告。

环境配置

需设置以下两个环境变量：

• PLAI_API_KEY — 您的 Plai API 密钥（从 Plai 账户控制台获取）
• PLAI_USER_ID — 您的 Plai 用户 ID

运行方式

所有操作均通过以下命令执行：

node scripts/plai-meta.js  [options]

选项以 --key value 形式传入。JSON 数组或对象值必须作为带引号的 JSON 字符串传入，例如：--locations '[{"id":"2537","type":"city","countryCode":"AE"}]'。

账户连接

此步骤必须在执行任何广告操作前完成。 若广告工具返回 "User has no connected Facebook account" 或类似提示，请生成账户连接链接并提供给用户，以便其完成 OAuth 流程。

生成账户连接链接

# 连接 Facebook / Instagram Ads 账户
node scripts/plai-meta.js create-connection-link --platform FACEBOOK

# 连接 Google Ads 账户
node scripts/plai-meta.js create-connection-link --platform GOOGLE

# 自定义连接完成后的跳转地址
node scripts/plai-meta.js create-connection-link 
  --platform FACEBOOK 
  --redirectUri "https://yourapp.com/connected"

必需参数：--platform（可选值：FACEBOOK 或 GOOGLE）
可选参数：--redirectUri — 用户完成 OAuth 后跳转的目标 URL

命令将返回一个 link，用户需在浏览器中打开该链接以完成账户连接。请直接将该链接提供给用户；切勿尝试自动打开。

广告系列管理

列出所有广告系列

node scripts/plai-meta.js list-campaigns

创建广告系列

node scripts/plai-meta.js create-campaign 
  --campaignName "My Campaign" 
  --campaignType LEAD_GENERATION 
  --budget 50 
  --url "https://example.com" 
  --locations '[{"id":"2537","type":"city","countryCode":"AE"}]' 
  --primaryText '[{"text":"Join us today!"}]' 
  --images '["https://example.com/image.jpg"]' 
  --leadsFormId "1234567890"

必需参数：campaignName、campaignType、budget、locations

按类型额外必需参数：

• LEAD_GENERATION → 还需提供 --leadsFormId
• CONVERSIONS / OUTCOME_SALES → 还需提供 --pixelId 和 --conversionGoal

可选参数：--url、--primaryText、--headlines、--images、--videos、--interests、--gender（"1" 表示男性 / "2" 表示女性）、--minAge、--maxAge、--targetLocales、--audienceId

注意事项：

• --images 接收一个 URL 字符串组成的 JSON 数组，系统会自动将其转换为 {url} 对象格式。
• --minAge 与 --maxAge 必须成对提供。
• callToAction 固定为 LEARN_MORE（由系统自动设定）。

campaignType 可选值：LEAD_GENERATION | LINK_CLICKS | CONVERSIONS | OUTCOME_SALES

创建消息互动广告系列

通过即时通讯应用（Messenger、Instagram DM、WhatsApp）引导用户开启对话。

node scripts/plai-meta.js create-message-engagement 
  --campaignName "Chat with Us" 
  --budget 50 
  --url "https://example.com" 
  --locations '[{"id":"2537","type":"city","countryCode":"AE"}]' 
  --messagingApps '["MESSENGER","WHATSAPP"]' 
  --multipleCreatives '[{
    "url": "https://example.com",
    "primaryText": "Chat with us today!",
    "greetingText": "Hi {{user_first_name}}! How can we help you?",
    "conversations": [{"title": "Learn more about our products"},{"title": "Get a quote"}],
    "image": "https://example.com/image.jpg"
  }]'

必需参数：campaignName、budget、url、locations、messagingApps、multipleCreatives

messagingApps — 值为包含以下项之一或多个的 JSON 数组：MESSENGER | INSTAGRAM | WHATSAPP — 务必向用户明确询问，不可设默认值。

multipleCreatives — 包含 1–10 个创意对象的 JSON 数组。每个创意对象需满足：

• 必需字段：url、primaryText、greetingText、conversations（由 {title} 对象构成的数组）
• 可选字段：headlines、phoneNumber、image（URL）、video（格式为 {video_id, thumbnail_url}）

其他可选广告系列参数：--interests、--gender、--minAge、--maxAge、--targetLocales、--audienceId

获取广告系列数据洞察

node scripts/plai-meta.js get-insights 
  --campaignId "123456789" 
  --startDate "2024-01-01" 
  --endDate "2024-01-31"

更新广告系列状态

node scripts/plai-meta.js update-status --campaignId "123456789" --status ACTIVE
node scripts/plai-meta.js update-status --campaignId "123456789" --status PAUSED
node scripts/plai-meta.js update-status --campaignId "123456789" --status DELETE

status 可选值：ACTIVE | PAUSED | DELETE

更新广告系列预算

node scripts/plai-meta.js update-budget --campaignId "123456789" --amount 100

线索表单

检查线索广告服务条款（TOS）

创建线索表单前必须执行此操作。若 TOS 尚未接受，用户需先访问 https://www.facebook.com/ads/leadgen/tos 完成签署。

node scripts/plai-meta.js check-leadform-tos

列出已有线索表单

node scripts/plai-meta.js list-leadforms

创建线索表单

所有字段值均需由用户提供 — 不得自行假设或伪造。

node scripts/plai-meta.js create-leadform 
  --leadsFormName "My Lead Form" 
  --privacyPolicyUrl "https://example.com/privacy" 
  --privacyPolicyName "Privacy Policy" 
  --website_url "https://example.com/thank-you" 
  --questionPageCustomHeadline "Tell us about yourself"

定向设置

搜索定向地区（创建广告系列前务必执行）

node scripts/plai-meta.js search-locations --query "Dubai"
node scripts/plai-meta.js search-locations --query "United States"

返回形如 {id, type, countryCode} 的对象。请将结果直接传入 create-campaign --locations。

搜索定向兴趣

node scripts/plai-meta.js search-interests --query "fitness"
node scripts/plai-meta.js search-interests --query "real estate" 
  --specialAdCategories '["HOUSING"]' 
  --specialAdCountries '["US","GB"]'

specialAdCategories 可选值：HOUSING | FINANCIAL_PRODUCTS_SERVICES | EMPLOYMENT

返回形如 {id, name, type} 的对象。请将结果传入 create-campaign --interests。

获取定向语言环境（语言定向）

node scripts/plai-meta.js get-locales

返回数字型语言环境 ID。请以 --targetLocales '[65,24]' 格式传入 create-campaign。

受众群体

列出自定义受众

node scripts/plai-meta.js list-audiences

创建主页互动受众

node scripts/plai-meta.js create-page-audience 
  --name "FB Page Engagers" 
  --type FACEBOOK

node scripts/plai-meta.js create-page-audience 
  --name "IG Engagers" 
  --type INSTAGRAM

创建线索表单受众

所有字段均为 必需 — 请明确向用户逐一索取。

node scripts/plai-meta.js create-leadform-audience 
  --name "Lead Form Openers" 
  --description "People who opened our summer campaign form" 
  --leadFormIds '["12345","67890"]' 
  --type open

type 可选值：open | close | submit

创建相似受众

node scripts/plai-meta.js create-lookalike 
  --sourceType AUDIENCE 
  --sourceId "120231334546180123" 
  --audienceName "Lookalike - US" 
  --countryCode US

sourceType 可选值：AUDIENCE（需配合 --sourceId 使用）| PAGE（无需 sourceId）

像素与转化事件

列出像素

node scripts/plai-meta.js list-pixels

列出某像素下的自定义转化事件

node scripts/plai-meta.js list-conversions 
  --pixelId "123456789" 
  --campaignType CONVERSIONS

campaignType 可选值：CONVERSIONS | OUTCOME_SALES

媒体资源

列出广告账户媒体

node scripts/plai-meta.js list-media --type IMAGE
node scripts/plai-meta.js list-media --type VIDEO

视频返回 {video_id, thumbnail_url} 结构。可在 create-campaign --videos 中使用。

列出 Facebook 主页媒体

node scripts/plai-meta.js list-fb-media --type IMAGE

列出 Instagram 主页媒体

node scripts/plai-meta.js list-ig-media

上传视频

node scripts/plai-meta.js upload-video --videoUrl "https://example.com/video.mp4"

返回 videoId。随后轮询查询其状态直至就绪：

node scripts/plai-meta.js get-video-info --videoId "123456789"

持续轮询直到 status 变为 READY，然后将 video_id 与 thumbnail_url 用于 create-campaign --videos。

商品目录

列出目录

node scripts/plai-meta.js list-catalogs

创建目录

node scripts/plai-meta.js create-catalog --name "My Store Catalog"

创建商品源（从指定 URL 导入商品）

node scripts/plai-meta.js create-catalog-feed 
  --catalogId "123456" 
  --name "Daily Feed" 
  --fileUrl "https://example.com/products.csv" 
  --currencyCode USD 
  --timezone "America/New_York" 
  --interval DAILY

获取商品源同步状态

node scripts/plai-meta.js get-catalog-feed --catalogFeedId "123456"

列出商品集合中的商品

node scripts/plai-meta.js list-catalog-products --productSetId "123456"

创建商品集合

node scripts/plai-meta.js create-product-set 
  --catalogId "123456" 
  --name "Summer Collection" 
  --productIds '["prod1","prod2","prod3"]'

工作流指南

创建广告系列前的必要步骤

1. 若 Meta 账户尚未连接，请运行 create-connection-link --platform FACEBOOK，并将返回的链接提供给用户。
2. 运行 search-locations 获取有效的地区 ID — 切勿猜测 ID。
3. 如需兴趣定向，可选运行 search-interests。
4. 对于 LEAD_GENERATION 类型：先运行 check-leadform-tos，再运行 list-leadforms 或 create-leadform。
5. 对于 CONVERSIONS/OUTCOME_SALES 类型：先运行 list-pixels，再运行 list-conversions。
6. 若计划复用现有广告账户媒体作为创意素材，请运行 list-media。

广告系列类型选择

广告系列创建后

广告系列默认以 暂停 状态创建。待用户确认准备上线后，请执行：

node scripts/plai-meta.js update-status --campaignId "" --status ACTIVE

错误处理