Web SDK - トラブルシューティングとベストプラクティス

フォローする
Avatar
Jared Ornstead
Updated
ドキュメント

概要

このガイドでは、トラッキングの問題を回避し、データの正確性を確保するための、一般的な実装上の問題、ベストプラクティス、解決策について説明します。

よくある実装エラー

エラー1：重複実装（ネイティブ＋GTM）

問題：最もよくあるエラーは、Native JavaScript SDKとGoogle Tag Manager SDKの両方を同時に実装することです。これにより、すべてのセッションとイベントが2回トラッキングされ、すべての指標が200%膨れ上がります。

重要Singularはイベントを自動的に重複排除しません。両方の実装方法を使用すると、すべてのデータが二重にカウントされます。

この問題を特定する方法

  • ウェブサイトのソースコードにSingular SDKスクリプトがないか確認してください。
  • GoogleタグマネージャーでSingularタグを確認する。
  • ブラウザの開発者ツールで、singular によってネットワークリクエストをフィルタリングし、ページロード時に発生するリクエスト数をカウントする（2ではなく1のはず）。

解決策

  1. 使いたい実装方法を決める（ネイティブJSを推奨）
  2. 他の実装を完全に削除する。
  3. イベントごとに1つのリクエストしか発生しないことをテストする。
  4. 24～48時間データを監視し、メトリクスが正常に戻ることを確認する。

エラー2：製品IDの形式が正しくない

問題：プロダクトIDの形式が間違っている。プロダクトIDは、すべてのサブドメインでWebアプリに一貫性を持たせる必要があります。

よくある間違い

  • ウェブサイトのURLを使用している： www.mycompany.com ❌
  • ダッシュを使用する:my-company-store ❌。
  • フォワードDNSの使用：mycompany.com.store ❌
  • スペースの使用:my company store ❌。

正しいフォーマット（逆DNS表記）：

  • com.mycompany ✓

ヒントProduct IDは、モバイルアプリのバンドル識別子のようなものだと考えてください。小文字を使用し、ドメインを逆から開始し、ドットを使用してコンポーネントを区切ります。

この問題を特定する方法

  • 開発者ツールでネットワークリクエストを確認する。
  • ブラウザの開発者ツールからリクエストペイロードのi パラメータを確認する。
  • ブラウザのコンソールでエラーを確認する

解決方法

  1. Singular Appsページから正しい値（BundleId）を取得する。
  2. 正しい形式で実装を更新する
  3. ネットワークリクエストの200ステータスコードをテストして確認する

エラー3：イベントが複数回発生する

問題：ページの再読み込み、ユーザーの急激なクリック、または重複排除ロジックの欠如により、イベントが複数回発生する。これにより、イベント数とコンバージョン数が増加する。

よくある原因

  • ユーザがボタンを何度もクリックする。
  • ページのレンダリングごとにイベントコードが実行される（React、Vue、Angularアプリ）
  • デフォルトの動作を妨げないフォーム送信
  • ページのリフレッシュや戻るボタンのナビゲーション
  • Google Tag Managerのトリガーが複数回実行される

重要いくつかの分析プラットフォームとは異なり、Singularはイベントを自動的に重複排除しません。重複トラッキングを防ぐ安全な仕組みを導入するのはあなたの責任です。

解決策

詳細は実装ガイドの戦略をご覧ください。ネイティブJS、GTM

エラー4：SDKが読み込まれません

問題：Singular SDKスクリプトがロードされず、トラッキングができない。

よくある原因

  • 広告ブロッカーによってスクリプトがブロックされている（主にGTMに影響します）
  • コンテンツセキュリティポリシー（CSP）の制限
  • スクリプトがページ上の間違った場所に配置されている
  • 実装コードの構文エラー
  • ネットワーク接続の問題

診断方法

  1. ブラウザの開発者ツールコンソール・タブを開く
  2. singular "または "sdk "に言及したエラーを探す。
  3. コンソールにtypeof singularSdk と入力してください。"undefined" ではなく、"function" を返すはずです。
  4. Networkタブでスクリプトのロードに失敗していないか確認する。
  5. 広告ブロッカーを無効にして、再度テストする

解決方法

  • 広告ブロッカー： ネイティブJavaScriptの実装に切り替える（ブロックされにくい）
  • CSPの問題：コンテンツ・セキュリティ・ポリシーにSingularドメインを追加する
  • スクリプトの配置：SDKスクリプトが<head> タグ内にあることを確認してください。
  • 構文エラー：JavaScriptコードの検証

コンテンツセキュリティポリシーの設定

ウェブサイトがCSPヘッダを使用する場合、以下のディレクティブを追加してください：

Content-Security-Policy: 
  script-src 'self' https://web-sdk-v1.singular.net;
  connect-src 'self' https://sdk-api-v1.singular.net;

ベストプラクティス

プロダクトIDの管理

  • ウェブサイトまたはウェブアプリごとに1つのプロダクトIDを使用する
  • すべてのページとサブドメインでプロダクトIDの一貫性を保つ
  • プロダクトIDをチームのナレッジベースに文書化する
  • 開発環境、ステージング環境、本番環境で別々のプロダクトIDを使用する

イベントの命名規則

適切な命名方法

  • 明確で説明的な名前を使用する：Purchase Signup_Completed,Video_Play
  • 大文字と小文字を区別する（Title_Caseを推奨）
  • スペースの代わりにアンダースコアを使う
  • 名前を32文字以内にする
  • 特殊文字や絵文字は避ける

悪い例

  • Purchase!!!🎉 (特殊文字や絵文字)
  • user clicked the purchase button on the checkout page (長すぎる、スペース）
  • evt_123 (説明的でない)

ヒント一貫性を保つために、マーケティング、プロダクト、エンジニアリングの各チームで共有するイベント名のドキュメントを作成しましょう。

イベントパラメータのベストプラクティス

  • 収益：文字列ではなく、常に数値で送信してください:revenue: "$49.99"ではなくrevenue: 49.99
  • 通貨：3文字のISO通貨コードを使用してください：USD EUR,GBP
  • ID：数字であっても文字列として送信する：product_id: "12345"
  • パラメータ名：一貫性を保つために snake_case を使う
  • 値：文字列の値は100文字以下に保つ

テスト戦略

立ち上げる前に、このテストチェックリストに従ってください：

表

テスト 検証方法 期待される結果
SDKがロードされる コンソールtypeof singularSdk "関数 "を返す
Init/PageVisitが追跡される ネットワークタブ：フィルタ "__PAGE_VISIT__" ページロード時にステータス200で1リクエスト
イベント発生 イベントをトリガーし、[Network]タブをチェックし、ペイロードでイベント名("n "パラメータ)を検証。 ステータス200のイベントごとに新しいリクエスト
製品IDが正しい リクエストのペイロードを確認し、ペイロードのイベント名（"i "パラメータ）を検証します。 リバースDNSフォーマット
重複なし 同じイベントを素早く3回トリガーする 送信されるリクエストは1回のみ
収益の追跡 購入イベントのペイロードをチェック 収益が数字で表示される
複数のページ 異なるページに移動 トラッキングはすべてのページで機能
モバイルデバイス iOSとAndroidのブラウザでテスト モバイルでもトラッキングが機能

パフォーマンスの最適化

  • SDKスクリプトを<head> タグに配置し、早期にロードする。
  • ページごとにトラッキングするイベント数を最小限にする（意味のあるアクション、マーケティングイベントにフォーカスする）
  • すべてのキーストロークのトラッキングを避ける（デバウンスを使用する）

プライバシーとコンプライアンス

クッキーの開示

設定でクロスサブドメイントラッキングを有効にすると、Singularはファーストパーティクッキーを設定します。プライバシーポリシーでこれを開示する必要があります。

推奨するプライバシーポリシーの文言

当社は、ユーザーの行動を追跡し、お客様のウェブサイト体験を向上させるためにクッキーを使用します。具体的には以下のクッキーを使用します：

singular_device_id- このクッキーは、当社のウェブサイトにアクセスしたユーザーに一意のIDを割り当てます。このIDは、個人情報を収集することなく、訪問中のユーザーの行動ややり取りを追跡するのに役立ちます。これにより、ユーザーを区別し、異なるセッションにわたる訪問者の行動を監視することができます。

  • 有効期間1年間
  • 種類ファーストパーティークッキー
  • プロバイダーSingular (https://www.singular.net/privacy-policy/)

GDPRとプライバシーコンプライアンス

GDPRコンプライアンス：

  • デフォルトでpersistentIdentifier: false
  • ユーザーの同意後にのみクッキーを有効にする
  • ユーザーがトラッキングをオプトアウトできるようにする
  • クッキーの同意バナーにSingularを含める

デバッグツールとテクニック

ブラウザ開発者ツール

デバッグ用のコンソールコマンド

// Check if SDK is loaded
typeof singularSdk
// Should return: "function"

// Test firing an event manually
window.singularSdk.event("test");

移行チェックリスト

他のアナリティクスプラットフォームから移行する場合、または実装をアップグレードする場合：

  1. 現在の実装を監査する
    • 現在トラッキングされているすべてのイベントを文書化する
    • トラッキングコードを含むすべてのページを特定する
    • カスタムパラメータやユーザーIDを記録する
  2. 新しい実装の計画
  3. 段階的に実装する
    • テスト／ステージング環境から始める
    • 徹底的にテストする（最低1週間）
    • トラフィックの少ない時期に本番環境にデプロイする
    • 旧システムと1-2週間並行運用
  4. データの検証
    • 新旧システム間のメトリクスの比較
    • 重複トラッキングのチェック
    • すべてのイベントが正しく実行されているか確認
    • 2～4週間モニタリング
  5. 旧システムの廃止
    • 古いトラッキングコードを削除
    • ドキュメントの更新
    • 新しいシステムでチームをトレーニング

ヘルプを得る

このガイドに記載されていない問題が発生した場合は、以下の手順に従ってください：

  • Singularカスタマーサクセスマネージャーにお問い合わせください。
  • Singularダッシュボードからサポートチケットを送信します。
  • ブラウザコンソールのログとネットワークリクエストのスクリーンショットを添付してください。
  • お客様のウェブサイトのURLと、問題を再現するための詳細な手順をお知らせください。

関連記事