リアルタイムデータアクセス

Zenovayからアナリティクスデータを取得して、独自のダッシュボードと監視ツールを構築します。

Zenovayはパブリックなウェブソケットストリームを公開していません。ダッシュボードは内部的にリアルタイムの訪問者アクティビティを表示しますが、独自の統合については、サポートされているパターンは外部APIのポーリングです。このガイドは、これを効率的に行う方法を示します。

リアルタイムデータはどこにあるか

ユースケース	最適なアプローチ
ライブ訪問者を自分で監視する	ダッシュボードのライブビュータブ（リアルタイムで更新）
カスタムダッシュボード	外部APIのポーリング
過去のデータ	rangeフィルター付き外部API
サイトにライブ訪問者カウンターを埋め込む	ウィジェット機能（自己完結的なHTMLウィジェット）

現在サイトに誰がいるかを確認するには、ウェブサイトのダッシュボードを開いてライブビュータブを選択します — 自動的に更新されます。以下のセクションでは、API上に独自の外部統合を構築する方法について説明します。

外部APIのポーリング

アナリティクスデータの場合は、APIキーで外部APIを使用します。ベースURLは次のとおりです：

https://api.zenovay.com/api/external/v1

以下のヘッダーのいずれかで認証します：

X-API-Key: zv_YOUR_API_KEY
Authorization: Bearer zv_YOUR_API_KEY

最近のアナリティクス

アナリティクスサマリーエンドポイントは range クエリパラメータを受け入れます（24h、7d、30d、90d、1y — デフォルト 7d）：

const API_KEY = process.env.ZENOVAY_API_KEY;
const WEBSITE_ID = 'your-website-id';

async function getRecentAnalytics() {
  const response = await fetch(
    `https://api.zenovay.com/api/external/v1/analytics/${WEBSITE_ID}?range=24h`,
    {
      headers: { 'X-API-Key': API_KEY }
    }
  );

  return await response.json();
}

外部APIのすべてのレスポンスは { success, data, timestamp } エンベロープでラップされており、合計は data.summary の下にあります：

{
  "success": true,
  "data": {
    "summary": {
      "total_visitors": 1247,
      "total_page_views": 3891,
      "unique_visitors": 1102
    },
    "time_range": "24h",
    "daily_stats": [ /* ... */ ]
  },
  "timestamp": "2026-06-13T00:00:00.000Z"
}

訪問者データ

async function getVisitors() {
  const response = await fetch(
    `https://api.zenovay.com/api/external/v1/analytics/${WEBSITE_ID}/visitors`,
    {
      headers: { 'X-API-Key': API_KEY }
    }
  );

  return await response.json();
}

data エンベロープ内では、visitors 配列と pagination オブジェクト（limit、offset、has_more）を返します。limit と offset クエリパラメータを使用して、結果をページネーションしてください。

カスタムダッシュボードの構築

React の例

import { useState, useEffect } from 'react';

function LiveDashboard({ websiteId, apiKey }) {
  const [analytics, setAnalytics] = useState(null);

  // レート制限を尊重するインターバルでアナリティクスサマリーを更新
  useEffect(() => {
    async function fetchAnalytics() {
      try {
        const response = await fetch(
          `https://api.zenovay.com/api/external/v1/analytics/${websiteId}?range=24h`,
          {
            headers: { 'X-API-Key': apiKey }
          }
        );
        const body = await response.json();
        // レスポンスは { success, data, timestamp } エンベロープでラップされています。
        setAnalytics(body.data);
      } catch (error) {
        console.error('Analytics fetch error:', error);
      }
    }

    fetchAnalytics();
    const interval = setInterval(fetchAnalytics, 5 * 60 * 1000);
    return () => clearInterval(interval);
  }, [websiteId, apiKey]);

  return (
    <div>
      {analytics && (
        <div>
          <h2>過去 24 時間</h2>
          <p>訪問者：{analytics.summary.total_visitors}</p>
          <p>ページビュー：{analytics.summary.total_page_views}</p>
          <p>ユニーク訪問者：{analytics.summary.unique_visitors}</p>
        </div>
      )}
    </div>
  );
}

レート制限に関する考慮事項

外部APIのレート制限はAPIキーごとであり、APIは有料のみです — フリー行は完全性のために表示されていますが、フリープランのキーは呼び出すことができません。

プラン	リクエスト/分	推奨ポーリング間隔
Free	利用不可	—
Pro	30	5分ごと
Scale	60	2分ごと
Enterprise	120	1分ごと

レスポンスには X-RateLimit-Limit および X-RateLimit-Remaining ヘッダーが含まれます（フォールバックパスで）。これらを読み取り、制限に近づくにつれてバックオフできます。

ベストプラクティス

• プランのレート制限が許可するより速くポーリングしないでください — アナリティクスデータは分単位で更新されます。秒単位ではありません。
• ポーリング間でレスポンスをローカルにキャッシュしてください。
• 指数バックオフでエラー処理を実装してください。
• ライブ訪問者を自分で見るには、ポーリングではなくライブビュータブを使用してください — それのために構築されています。

次のステップ

• REST API リファレンス
• API 概要
• APIキーを取得する