Customer.io の既知の落とし穴

概要

Customer.io との統合時に発生する一般的な間違いとアンチパターンを回避します。

落とし穴のカテゴリ

1. 認証とセットアップ

落とし穴: Track API に App API キーを使用する

// WRONG: Track API に App API キーを使用
const client = new TrackClient(siteId, appApiKey); // 失敗します！

// CORRECT: Track API キーを使用して追跡
const client = new TrackClient(siteId, trackApiKey);

// App API キーはトランザクション API とレポート API にのみ使用
const apiClient = new APIClient(appApiKey);

落とし穴: ミリ秒単位のタイムスタンプ

// WRONG: JavaScript のミリ秒
{ created_at: Date.now() } // 1704067200000 - 拒否されます！

// CORRECT: Unix 秒
{ created_at: Math.floor(Date.now() / 1000) } // 1704067200

落とし穴: ハードコードされた認証情報

// WRONG: コード内の認証情報
const client = new TrackClient('abc123', 'secret-key'); // セキュリティリスク！

// CORRECT: 環境変数
const client = new TrackClient(
  process.env.CUSTOMERIO_SITE_ID!,
  process.env.CUSTOMERIO_API_KEY!
);

2. ユーザー識別

落とし穴: 識別前にイベントを追跡する

// WRONG: 識別前に追跡
await client.track(userId, { name: 'signup' }); // ユーザーが存在しません！
await client.identify(userId, { email: 'user@example.com' });

// CORRECT: 常に最初に識別
await client.identify(userId, { email: 'user@example.com' });
await client.track(userId, { name: 'signup' });

落とし穴: ユーザー ID を変更する

// WRONG: メールアドレスが変更されるとユーザー ID も変わる
const userId = user.email; // メール変更 = 新規ユーザー！

// CORRECT: 不変の識別子を使用
const userId = user.databaseId; // UUID または自動採番 ID

落とし穴: 匿名 ID がマージされない

// WRONG: anonymous_id リンクなし
await client.identify(newUserId, { email: 'user@example.com' });
// 匿名アクティビティは孤立します！

// CORRECT: マージのために anonymous_id を含める
await client.identify(newUserId, {
  email: 'user@example.com',
  anonymous_id: previousAnonymousId
});

3. イベント追跡

落とし穴: 一貫性のないイベント名

// WRONG: 一貫性のないケースと命名規則
await client.track(userId, { name: 'UserSignedUp' });
await client.track(userId, { name: 'user-signed-up' });
await client.track(userId, { name: 'user_signedup' });

// CORRECT: 一貫性のある snake_case
await client.track(userId, { name: 'user_signed_up' });

落とし穴: 一意のイベントが多すぎる

// WRONG: 動的なイベント名は乱雑になる
await client.track(userId, { name: `viewed_product_${productId}` });
// 数千の一意のイベントが作成されます！

// CORRECT: バリエーションにプロパティを使用
await client.track(userId, {
  name: 'product_viewed',
  data: { product_id: productId }
});

落とし穴: アナリティクスの処理でブロックする

// WRONG: リクエストパスでアナリティクスを待つ
app.post('/signup', async (req, res) => {
  const user = await createUser(req.body);
  await client.identify(user.id, { email: user.email }); // ブロック！
  res.json({ user });
});

// CORRECT: ファイア・アンド・フォーゲット
app.post('/signup', async (req, res) => {
  const user = await createUser(req.body);
  client.identify(user.id, { email: user.email })
    .catch(err => console.error('Customer.io error:', err));
  res.json({ user });
});

4. データ品質

落とし穴: 必須属性がない

// WRONG: メール属性がない
await client.identify(userId, { name: 'John' });
// ユーザーはメールを受信できません！

// CORRECT: メールキャンペーン用にメールを常に含める
await client.identify(userId, {
  email: 'john@example.com',
  name: 'John'
});

落とし穴: 一貫性のない属性タイプ

// WRONG: 時には文字列、時には数値
await client.identify(userId1, { plan: 'premium' });
await client.identify(userId2, { plan: 1 });

// CORRECT: 一貫性のあるタイプ
await client.identify(userId, { plan: 'premium' });

落とし穴: セグメント名またはイベント名に PII を含める

// WRONG: PII が露出
await client.track(userId, { name: `email_${user.email}` });
// セグメントが作成: "email_john@example.com"

// CORRECT: 名前ではなく属性を使用
await client.track(userId, {
  name: 'email_action',
  data: { email: user.email }
});

5. キャンペーン設定

落とし穴: 配信停止処理がない

## WRONG: 配信停止リンクなし
{{{ unsubscribe_url }}} なしのメールテンプレート

## CORRECT: 常に配信停止を含める
<a href="{{{ unsubscribe_url }}}">Unsubscribe</a>

落とし穴: すべての属性更新でトリガーを実行

# WRONG: すべての識別でトリガーが実行される
trigger:
  event: "identify"

# CORRECT: 特定のイベントでトリガーを実行
trigger:
  event: "signed_up"

6. 配信の問題

落とし穴: バウンスを無視する

// WRONG: バウンス処理がない
webhooks.on('email_bounced', () => {
  // 何もしない
});

// CORRECT: バウンスで抑制または更新
webhooks.on('email_bounced', async (event) => {
  await client.suppress(event.data.customer_id);
  // またはデータベース内でメールを無効としてマーク
});

落とし穴: 苦情率を監視しない

// WRONG: スパム苦情を無視
// 配信可能性に問題が生じます！

// CORRECT: 苦情をアラート
webhooks.on('email_complained', async (event) => {
  // すぐに抑制
  await client.suppress(event.data.customer_id);
  // チームにアラート
  await alertTeam(`Spam complaint from ${event.data.email_address}`);
});

7. パフォーマンスの問題

落とし穴: コネクションプーリングがない

// WRONG: リクエストごとに新しいクライアント
app.get('/api', async (req, res) => {
  const client = new TrackClient(siteId, apiKey); // 新しい接続を作成！
  await client.identify(userId, data);
});

// CORRECT: クライアントを再利用
const client = new TrackClient(siteId, apiKey);
app.get('/api', async (req, res) => {
  await client.identify(userId, data);
});

落とし穴: レート制限がない

// WRONG: 制御されないバースト
for (const user of users) {
  await client.identify(user.id, user.data); // 10,000 件のリクエストが一気に！
}

// CORRECT: レート制限
const limiter = new Bottleneck({ maxConcurrent: 10, minTime: 10 });
for (const user of users) {
  await limiter.schedule(() => client.identify(user.id, user.data));
}

アンチパターン検出スクリプト

// scripts/audit-integration.ts
interface AuditResult {
  issues: string[];
  warnings: string[];
  score: number;
}

async function auditIntegration(): Promise<AuditResult> {
  const result: AuditResult = { issues: [], warnings: [], score: 100 };

  // ハードコードされた認証情報をチェック
  const files = await glob('**/*.{ts,js}');
  for (const file of files) {
    const content = await readFile(file, 'utf-8');
    if (content.includes('site_') && content.includes('api_')) {
      result.issues.push(`Possible hardcoded credentials in ${file}`);
      result.score -= 20;
    }
  }

  // ミリ秒単位のタイムスタンプをチェック
  if (await hasPattern(/Date\.now\(\)(?!\s*\/\s*1000)/)) {
    result.warnings.push('Possible millisecond timestamps detected');
    result.score -= 5;
  }

  // track before identify パターンをチェック
  if (await hasPattern(/track\([^)]+\)[\s\S]{0,500}identify\(/)) {
    result.issues.push('Track before identify pattern detected');
    result.score -= 15;
  }

  return result;
}

クイックリファレンス

落とし穴	修正
誤った API キー	Track API は追跡用、App API はトランザクション用
ミリ秒	Math.floor(Date.now() / 1000) を使用
識別前に追跡	常に最初に識別
ユーザー ID を変更	不変のデータベース ID を使用
メール属性がない	メールキャンペーン用にメールを含める
動的なイベント名	代わりにプロパティを使用
リクエストをブロック	ファイア・アンド・フォーゲットパターン
バウンス処理がない	バウンス時に抑制
レート制限がない	Bottleneck または類似のツールを使用

リソース

• Customer.io Best Practices
• Common Issues

まとめ

これらのガイドラインに従うことで、一般的な落とし穴を回避し、信頼性の高い Customer.io 統合を構築できます。このチェックリストに照らして定期的に実装を監査し、問題を早期に発見してください。