モダンエッジスタックで構築する動画アドネットワーク

モダンエッジスタックで構築する 動画アドネットワーク Cloudflare Workers, Turso, Hono, Kyselyによる実践アーキテクチャ

フルスクラッチで構築した 動画アドネットワーク 概要 動画・音声広告を配信するアドネット ワークをゼロから構築。 構成: 広告サーバー、管理画面、クライア ントSDK、データベース層の4つの主要コ ンポーネントで構成。 管理: これらすべてをpnpmワークスペースと Turborepoを用いたモノレポで一元管理。 広告サーバー 管理画面 SDK データベース

The Journey of an Ad Request: 広告リクエストの旅路 「1つの広告リクエストがユーザーのブラウザで発生し、我々のシステムを巡り、動画が再生され、 データとして記録されるまでの一連の旅を、この図に沿って追いかけていきます。」 Ad SDK メディアサイト Ad Server (Cloudflare Workers) Database (Turso)

Step 1. 旅の始まり - The Request ・トリガー メディアサイトが `packages/ad-sdk`を読み込み、 `initializeAdSDK`関数を呼び出 す。 ・アクション SDKが広告サーバー (`apps/ad-server`)に対して、 広告情報を要求するVASTリクエ ストを送信する。 Ad Server (Cloudflare Workers) ユーザー (ブラウザ)

Step 2. エッジでの意思決定 - The Decision 実行環境: Cloudflare Workers上で動作 するHonoアプリケーションがリクエスト を処理。 広告選定: 配信可能なキャンペーンの中 から、最適な広告を選択。 フリークエンシーキャップ: `ad_frequency` Cookieを読み取り、同 一ユーザーへの広告表示回数を制御。 上限に達していれば別の広告を選択す る。 レスポンス: 選択された広告情報に基づ き、VAST XMLを生成してクライアント に返却する。 Cookie Ad Server (Cloudflare Workers) Database (Turso)

Step 3. 価値の具現化 - The Playback SDKの役割: 返却されたVAST XMLをパース し、<video>要素を動的に生成して動画再生 を開始する。 VAST 4.1準拠: IABの標準規格に準拠。XMLに は主に以下の情報が含まれる。 • MediaFiles: 動画ファイルのURL • VideoClicks: クリック遷移先URL • TrackingEvents: 各種トラッキングイベン ト用のURL • CompanionAds: 動画に付随するバナー広 告 (例: 300x250)

Step 4. フィードバックループ - The Tracking 発火イベント: SDKは動画の再生状況に応じ て、適切なタイミングでトラッキングイベン トを発火させる。 Impression: 再生開始時. Progress: 再生進捗が25%, 50%, 75%, 100%に到達した時点. Click: ユーザーが動画をクリックした時点. 仕組み: 各イベントはトラッキングエンドポ イント (/v1/impressionなど) を呼び出す。 サーバーは1x1の透明GIFを返し、 ad_eventsテーブルにイベントを記録する。 ユーザー識別にはuid Cookieを使用。 Ad Server (Cloudflare Workers)

アーキテクチャ: 旅を支える4つのパッケージ モノレポは、責務が明確に分離された4つの 主要パッケージで構成されている。 • apps/ad-server: Hono on CF Workers。 広告配信APIとトラッキングサーバー。 • apps/ui: React Router v7 on CF Workers。 広告主・メディア向け管理画面。 • packages/ad-sdk: JavaScript SDK。 メディアサイトに埋め込まれ、広告再生と トラッキングを担う。 • packages/db: Kysely + Atlas。型安全な データベースアクセス層。 Ad SDK Database

データ層の心臓部: Turso, Atlas, Kysely データベースエンジン: Turso (本番) と ローカルSQLite (開発)。libSQLベースの 分散DBにより、エッジからの低遅延アクセ スを実現。 スキーマ管理: Atlas。`schema.sql`にス キーマを宣言的に記述し、`atlas migrate diff`コマンドで差分マイグレーションSQL を生成。 クエリビルダー: Kysely。`kysely- codegen`を用いてDBスキーマからType Scriptの型を自動生成し、完全な型安全性 を実現。`CamelCasePlugin`で命名規則の 違いも吸収。 Turso Kysely Atlas schema.sql

開発からデプロイまでの舞台裏 開発環境: pnpmワークスペースとTurborepoでモノレポを効率的に管理。`turso dev`でロー カルDBを起動。Biome (Linter), Prettier (Formatter) でコード品質を統一。 デプロイフロー: GitHub ActionsでCI/CDを構築。 1. mainブランチへのプッシュをトリガー。 2. AtlasがTursoへDBマイグレーションを適用。 3. Wranglerが`ad-server`と`ui`をCloudflare Workersにデプロイ。 環境変数: TURSO_DATABASE_URLなどをGitHub Secretsで安全に管理。 Develop Commit CI/CD Deploy Cloudflare Global Network

運用を支える管理画面 スタック: React Router v7をCloudflare Workers上で動作させることで、管理画 面もエッジで実行。 認証: better-authを利用し、組織ベース のマルチテナント認証を実装。 機能: • 広告主向け: キャンペーン>クリエイ ティブの階層管理。 • メディア向け: 広告枠とコンパニオン スロットの設定。 • 共通: `daily_reports`テーブルから集 計されたパフォーマンスレポートの閲 覧。 パフォーマンスレポート daily_reports daily_reports

技術選定を貫く3つのフィロソフィー 1. Edge First Cloudflare WorkersとTursoの組み合わ せにより、グローバル規模での低遅延な広 告配信を実現。すべての処理を可能な限り ユーザーに近い場所で実行する。 2. Type Safety KyselyとTypeScriptを徹底活用。スキー マ変更時のミスをコンパイル時に防ぎ、実 行時エラーを削減することで、システム の堅牢性と開発者の生産性を両立。 3. Standard Compliance VAST 4.1という業界標準に準拠。既存の 動画プレイヤーやDSP (Demand-Side Platform) との相互運用性を確保し、エ コシステム内での連携を容易にする。

まとめ: モダンエッジスタックによる価値実現 • Cloudflare Workers, Turso, Honoと いったモダンなエッジスタックを用 いて、広告業界特有の要件を満たす 高さパフォーマンスな配信システム を構築した。 • Cookieベースのフリークエンシーキ ャップや、標準規格VASTに準拠したト ラッキングを実装し、事業要件を達成 した。 • Atlasによる宣言的マイグレーション と、Kyselyによる完全な型安全性を組 み合わせることで、堅牢かつ快適なデー タベース開発体験を実現した。