customerio-install-auth

用途

本技能用于安装并配置 Customer.io 的 SDK/CLI 认证，适用于设置新的 Customer.io 集成、配置 API 密钥或初始化 Customer.io 客户端。其目标是产出一份针对目标工作区/环境的、作用域受限的 Customer.io 凭据参考，并通过一次低影响的连接测试进行验证，同时形成密钥管理与轮换记录，确保令牌不进入代码仓库、shell 历史或日志。

主要能力

• 安装 customerio-node SDK。
• 配置 Customer.io 两套 API 的认证：Track API（识别用户、追踪事件）与 App API（事务性消息、广播、数据查询）。
• 创建并复用 TrackClient 与 APIClient 单例。
• 通过低影响操作验证连接。
• 支持 US 与 EU 区域配置。
• 提供常见错误处理与凭据安全建议。

前置条件

• Node.js 18+ 及 npm/pnpm。
• Customer.io 账户（https://fly.customer.io）。
• 来自 Settings > Workspace Settings > API & Webhook Credentials 的 Site ID 与 Track API Key。
• 同一页面提供的 App API Key（bearer token），用于事务性消息和广播。

两套 API、两个客户端

客户端	认证方式	密钥来源	用途
TrackClient	Basic Auth（Site ID + API Key）	Track API 凭据	identify()、track()、trackAnonymous()、suppress()、destroy()
APIClient	Bearer Token（App API Key）	App API 凭据	sendEmail()、sendPush()、triggerBroadcast()

使用方式

第 1 步：安装 SDK

npm install customerio-node

该包导出 TrackClient、APIClient、RegionUS、RegionEU、SendEmailRequest 和 SendPushRequest。

第 2 步：配置环境变量

# .env — NEVER commit this file
CUSTOMERIO_SITE_ID=your-site-id-here
CUSTOMERIO_TRACK_API_KEY=your-track-api-key-here
CUSTOMERIO_APP_API_KEY=your-app-api-key-here
CUSTOMERIO_REGION=us          # "us" or "eu"

如果尚未添加，请将 .env 加入 .gitignore。

第 3 步：创建 Track 客户端

// lib/customerio.ts
import { TrackClient, RegionUS, RegionEU } from "customerio-node";

function getRegion() {
  return process.env.CUSTOMERIO_REGION === "eu" ? RegionEU : RegionUS;
}

// Singleton — reuse across your app
let trackClient: TrackClient | null = null;

export function getTrackClient(): TrackClient {
  if (!trackClient) {
    const siteId = process.env.CUSTOMERIO_SITE_ID;
    const apiKey = process.env.CUSTOMERIO_TRACK_API_KEY;
    if (!siteId || !apiKey) {
      throw new Error(
        "Missing CUSTOMERIO_SITE_ID or CUSTOMERIO_TRACK_API_KEY"
      );
    }
    trackClient = new TrackClient(siteId, apiKey, { region: getRegion() });
  }
  return trackClient;
}

第 4 步：创建 App API 客户端

// lib/customerio-app.ts
import { APIClient, RegionUS, RegionEU } from "customerio-node";

let appClient: APIClient | null = null;

export function getAppClient(): APIClient {
  if (!appClient) {
    const appKey = process.env.CUSTOMERIO_APP_API_KEY;
    if (!appKey) {
      throw new Error("Missing CUSTOMERIO_APP_API_KEY");
    }
    const region =
      process.env.CUSTOMERIO_REGION === "eu" ? RegionEU : RegionUS;
    appClient = new APIClient(appKey, { region });
  }
  return appClient;
}

第 5 步：验证连接

// scripts/verify-customerio.ts
import { getTrackClient } from "../lib/customerio";

async function verify() {
  const cio = getTrackClient();
  try {
    // Identify a test user — if credentials are wrong, this throws
    await cio.identify("test-verify-user", {
      email: "verify@example.com",
      created_at: Math.floor(Date.now() / 1000),
    });
    console.log("Customer.io connection verified successfully");
    // Clean up: suppress the test user
    await cio.suppress("test-verify-user");
    console.log("Test user suppressed");
  } catch (err: any) {
    console.error("Connection failed:", err.statusCode, err.message);
    process.exit(1);
  }
}

verify();

运行：npx tsx scripts/verify-customerio.ts

区域配置

区域	Track API Base URL	App API Base URL	SDK 常量
US	https://track.customer.io	https://api.customer.io	RegionUS
EU	https://track-eu.customer.io	https://api-eu.customer.io	RegionEU

区域在创建 Customer.io 账户时设定。可在 Settings > Workspace Settings 确认。EU 账户必须指定 RegionEU，否则所有 API 调用都会以 401 失败。

错误处理

错误	原因	解决方案
401 Unauthorized	Site ID 或 Track API Key 错误	在 Customer.io Settings > API & Webhook Credentials 中核对两个值
App API 返回 401	App API Key 错误或误用了 Track 密钥	App API 使用不同的 bearer token——检查 App API 密钥
区域不匹配	EU 账户使用了 US 端点	设置 CUSTOMERIO_REGION=eu 并使用 RegionEU
ENOTFOUND	DNS 解析失败	检查网络、代理或防火墙是否阻止 track.customer.io
MODULE_NOT_FOUND	SDK 未安装	运行 npm install customerio-node

安全说明

• 生产环境应将凭据存储在密钥管理器（GCP Secret Manager、AWS SSM、Vault）中。
• Track API Key 可以识别/追踪用户，但不能发送消息——风险较低。
• App API Key 可以发送消息并访问数据——应视为高度敏感。
• 每 90 天通过 Settings > API & Webhook Credentials > Regenerate 轮换密钥。

适用场景

• 新建 Customer.io 集成并需要配置认证。
• 需要区分 Track API 与 App API 两套凭据的客户端初始化。
• 需要验证凭据连通性并处理区域、错误与密钥安全。

限制

• 依赖 Node.js 18+ 环境。
• 需要有效的 Customer.io 账户与对应凭据。
• EU 账户必须显式指定区域，否则调用失败。
• 资料未提供 CLI 的具体安装与使用细节。

后续步骤

认证成功后，可继续使用 customerio-hello-world 完成首次 identify + track 调用。