shop_campaign_insights スキーマが追加。広告費・売上・注文数・ROAS・AOV・平均顧客獲得コストを、既存の shopifyqlQuery フィールドと read_reports スコープのまま取得できる。新しいスコープも追加実装も不要。
shop_campaign_insights スキーマが追加された。shopifyqlQuery フィールド ＋ read_reports スコープでそのまま照会できる。
ShopifyQL では他のスキーマは照会できたが、Shop Campaigns の成果データを引く shop_campaign_insights は用意されていなかった。
同じ shopifyqlQuery にスキーマ名を書くだけ。すでに ShopifyQL を叩いているアプリなら、新しいスコープも連携実装も不要と明記されている。
shopifyqlQuery、権限も今まで通り read_reports。
増えたのは「照会先スキーマ名」の選択肢だけ、という設計になっている。
| 切り口 | 内容 |
|---|---|
| キャンペーン名 | キャンペーン単位（campaign-level）で指標を分解できる |
| カスタマーセグメント | セグメント単位（segment-level）で指標を分解できる |
| 時間 | 時間単位 〜 年単位 hourly / …／ yearly まで。マーチャントのショップのタイムゾーンで返る |
| 項目 | 今回の変更 |
|---|---|
| スキーマ | 追加 shop_campaign_insights が ShopifyQL で利用可能に |
| 呼び出しフィールド | 変更なし 既存の shopifyqlQuery をそのまま使う |
| 必要スコープ | 変更なし read_reports。新しいスコープは不要 |
| 連携実装 | すでに ShopifyQL を照会しているなら追加の連携作業は不要と明記 |
| 実行主体 | アナリティクス／レポーティングアプリが許諾済みマーチャントの代理として照会 |
| タイムゾーン | マーチャントのショップのタイムゾーン基準で返る |
read_reports スコープ既存の ShopifyQL 照会と同じスコープ。これ以上のスコープ追加は不要。
「authorized merchants」の代理としての照会。許諾されたストアのデータのみが対象。
すでに shopifyqlQuery を使っていれば、そのコードパスを流用できる。
read_reports があるか確認。既に ShopifyQL を叩いているなら通常そのまま。
同じ shopifyqlQuery で shop_campaign_insights を照会する。
キャンペーン名／セグメント／時間粒度（時〜年）を指定してレポート化する。
Shop Campaigns の指標を自アプリの UI に直接埋め込めるウェブコンポーネント。データの保存が不要（no data storage required）と明記されている。自前でメトリクスを取得・保管・描画する実装を持たずに、画面に出せるルート。
マーチャントのアナリティクスのチャート上に注釈（アノテーション）を作成できる API。記事の例は「campaign started（キャンペーン開始）」「budget changed（予算変更）」。数値の変化点に「なぜ動いたか」を貼れる。
エンドポイントも認可も既存のまま。shopifyqlQuery のラッパーを持っているアプリなら、スキーマ名を通す引数を足す程度で届く。差分レビューが小さく済む種類の変更。
read_reports のまま ＝ 再認可フロー不要スコープ追加は既存インストール全体への再同意を意味するのが普通。今回はそれが要らないと明記されているため、マーチャントへの再承認依頼なしで配れるのが実務上いちばん大きい。
hourly 〜 yearly。時間帯別の投下効率まで見られる一方、細かい粒度でレンジを広く取ればレスポンスは重くなる。粒度とレンジの上限はアプリ側で設計しておくのが安全。
返る時間軸は マーチャントのショップのタイムゾーン。自社ダッシュボードを UTC や JST 固定で組んでいると、他データソースと日付境界がズレる。突合するなら変換方針を先に決める。
同じ指標を出すのに、ShopifyQL で取得して自前で描画するルートと、Analytics Web Components で埋め込む（データ保存不要）ルートの 2 つが同時に提供された。加工・突合・エクスポートが要るなら ShopifyQL、単に画面に出したいだけならコンポーネントの方が実装量は小さい。両方を作り込む前に、どちらで足りるかを決めておく。
shopifyqlQuery 呼び出しに shop_campaign_insights のクエリを追加し、キャンペーン名 × 期間で広告費／売上／注文数／ROAS を表に出す。shop_campaign_insights スキーマで引けるようになった。shopifyqlQuery と read_reports のまま、新スコープも追加連携もなしで、レポートにキャンペーン成果を足せる。