SafeFrame API リファレンス

[アーティクル]
02/26/2024

SafeFrame は、API 対応のマネージド iframe です。これにより、パブリッシャーページコンテンツと、広告などの iframe に含まれる外部コンテンツとの間のコミュニケーションの行が開きます。ホストによって提供されるセカンダリドメインで動作し、理想的にはコンテンツ配信ネットワーク (CDN) 上に確立されます。このセカンダリドメインは、ホストと外部パーティの間の非依存の処理領域として機能します。外部パーティがホストドメインについて知る必要がある情報は、SafeFrame API を使用して要求によってアクセスされます。この API は、SafeFrame: sf-ext.js の Xandr のソリューションを使用して、ホストサイトと外部コンテンツ間の通信に使用されます。これは AST を使用して構築されましたが、別のコンポーネントとして提供されます。

SafeFrame 機能には多くの利点があります。これには、コンシューマーの保護、発行元の制御、効率性が含まれます。

SafeFrame とビデオ

ビデオのお客様の場合、SafeFrame は現在、アウトストリームビデオの配置でのみサポートされています。この機能を使用する場合は、 Microsoft Advertising ヘルプセンターでアウトストリームビデオのページ上のタグを設定するためのガイドラインに従っていることを確認してください。

実装と関数

これは、クリエイティブがアクセスできる API に関連します。
通信には、次の関数を使用できます。これらの関数は、 IAB 仕様に従って実装されます。

関数	説明
`$sf.ext.collapse`	collapse 関数は、SafeFrame コンテナーを元の幾何学的位置に折りたたみます。
`$sf.ext.expand`	expand 関数は、SafeFrame コンテナーを指定された幾何学的位置に展開し、中間的な展開を可能にします。これは、両方のプッシュモードでの拡張をサポートしています。
`$sf.ext.geom`	geom 関数を使用すると、SafeFrame コンテナーの幾何学的寸法と場所を交換できます。これには、ブラウザーまたはアプリケーションウィンドウに関連するコンテンツと、ホストコンテンツが表示されているデバイスの画面境界が含まれます。
`$sf.ext.inViewPercentage`	コンテナーが画面に表示されている領域の割合を、0 から 100 の整数として返します。これは IAB 仕様に従います。詳細については、こちらをご覧ください。
`$sf.ext.register`	外部パーティレジスタ関数は、SafeFrame 外部パーティ API 呼び出しを受け入れるために SafeFrame プラットフォームを登録します。外部パーティークリエイティブは、最初の (折りたたまれた) 幅と高さを宣言します。幅と高さに加えて、この関数は、さまざまな状態の詳細について外部コンテンツに通知するコールバック関数を定義することもできます。
`$sf.ext.status`	status 関数は、コンテナーの現在の状態に関する情報を返します。状態: 展開、展開、折りたたみ、折りたたみ
`$sf.ext.supports`	supports 関数は、特定の機能 (拡張、プッシュモード、Cookie の読み取り、Cookie コンテナーの書き込み) を表すキーを持つオブジェクトを返します。
`$sf.ext.winHasFocus`	SafeFrame が含まれているブラウザーウィンドウまたはタブにフォーカスがあるか、現在アクティブであるかを返します。

apntag.defineTag({param})

SafeFrame コンテナーでクリエイティブをdefineTag配信するパラメーター 'enableSafeFrame' が追加されます。

パラメーター

名前	型	説明
`enableSafeFrame`	ブール値	SafeFrame コンテナーにクリエイティブを配信します。
`setSafeFrameConfig`	ブール値	標準 iframe によって提供される以外の追加のコンシューマー保護と発行元制御を提供するマネージド iframe である SafeFrame の構成を許可します。

例

 
var tag = apntag.defineTag({
            enableSafeFrame : true,
            tagId : 10107529, //10066308,
            sizes : [[300,250]],
            targetId: 'apn_ad_40954389053',
           //new field
            safeframeConfig: {
              allowExpansionByPush:true,
              allowExpansionByOverlay:true
            }
          //end new field
        });

apntag.setSafeFrameConfig({param})

この関数を使用して、SafeFrame を構成できます。 SafeFrame 拡張 API には、 allowExpansionByPush 2 つのオプションが allowExpansionByOverlay 用意されています。この関数による構成では、関数の戻り値が $sf.ext.supports 変更されます。パブリッシャーは、ここから展開アクセス許可を取り消すことができます。

パラメーター

名前	型	説明
`allowExpansionByPush`	ブール値	ホストは、このパラメーターを使用してプッシュによって拡張を切り替えることができます。
`allowExpansionByOverlay`	ブール値	ホストは、このパラメーターを使用してオーバーレイによって拡張を切り替えることができます。

例

apntag.setSafeFrameConfig({
        "allowExpansionByPush" : true,
        "allowExpansionByOverlay" : true
});

apntag.setPageOpts({param})

パラメーター enableSafeFrame が関数に setPageOpts 追加されます。このパラメーターは、SafeFrame を有効にし、SafeFrame コンテナー内のすべての広告を提供します。

パラメーター

名前	型	説明
`enableSafeFrame`	ブール値	セーフフレームコンテナー内のすべてのクリエイティブを配信します。

例

apntag.setPageOpts({
        //other setPageOpts params
        "enableSafeFrame" : true
});

注:

ページレベル関数: すべての AST 関数はページレベルになります。クリエイティブ関数: $sf.ext 関数はすべてクリエイティブによって呼び出されます。

セーフフレーム API 関数の例

次の例では、SafeFrame の API 関数を使用する方法を示します。

$sf.ext.register(width, height, callbackFn)

SafeFrame 外部 API レジスタ関数は、SafeFrame 外部パーティ API 呼び出しを受け入れるために関数を登録します。外部パーティークリエイティブは、さまざまな状態の詳細について外部コンテンツに通知する初期 (折りたたまれた) 幅と高さとコールバック関数を宣言します。

パラメーター

名前	型	説明
`callbackFn`	function	任意の操作で呼び出される関数。
`height`	番号	クリエイティブの初期高さ
`width`	番号	クリエイティブの初期幅

例

var statusUpdate = function(status) {
        if(status === 'expanded') {
                //do something
        } else if(status == 'collapsed') {
                //do something
        }
}
$sf.ext.register('300','250',statusUpdate);

$sf.ext.supports()

この関数は、この特定のコンテナーで有効または無効になっている機能を表すキーを持つオブジェクトを返します。

例

var supports = $sf.ext.supports();
if(supports['exp-ovr']) {
        //expansion by overlay is supported so expand can be called safely with overlay param
}
if(supports['exp-push']) {
        //expansion by push is supported so expand can be called safely with push param
}

$sf.ext.geom()

この関数は、を囲んで targetDiv SafeFrame コンテナーを展開するために使用できる領域を取得します。次のオブジェクトが返されます。

例

 var g = $sf.ext.geom();
 if (/*check available space to expand before calling expand function*/) {
      $sf.ext.expand(obj);
 }

スクロール位置の例

 var geom = $sf.ext.geom();
 geom.anx.scrollTop; // scrollTop
 geom.anx.scrollLeft; // scrollLeft

これは、AST が iframe 内にある場合の中間の同じドメイン iframe の最終的なスクロール位置を考慮します。

注:

geom.anx はセーフフレーム仕様に対する独自の拡張機能です。

$sf.ext.expand({params})

この関数は、SafeFrame コンテナーを指定された幾何学的位置に展開します。すべてのパラメーターは必須であるため、左に展開しない場合は、'left' を保持するよりも 0

パラメーター

名前	型	説明
`b`	番号	現在の上座標(y+高さ)を基準とした新しい下座標 (y+高さ)。
`l`	番号	現在の左座標を基準とした新しい左座標 (x)。
`push`	ブール値	オーバーレイではなく、展開でホストコンテンツをプッシュする必要があるかどうか。
`r`	番号	現在の右座標 (x+ 幅) を基準とした新しい右座標 (x+ 幅)。
`t`	番号	現在の上座標を基準とした新しい上座標 (y)。

例

$sf.ext.expand({
        'l' : 0,
        'r' : 0,
        't' : 0,
        'b' : 500,
        'push' : true
});

$sf.ext.collapse()

この関数は、SafeFrame コンテナーを元の幾何学的位置に折りたたみます。

例

$sf.ext.collapse();

$sf.ext.status()

この関数は、SafeFrame コンテナーの現在の状態を返します。使用できる状態は、 expanded、 collapsed、です ready。

例

$sf.ext.status();

次の方法で共有

SafeFrame API リファレンス

SafeFrame とビデオ

実装と関数

apntag.defineTag({param})

パラメーター

例

apntag.setSafeFrameConfig({param})

パラメーター

例

apntag.setPageOpts({param})

パラメーター

例

セーフフレーム API 関数の例

$sf.ext.register(width, height, callbackFn)

パラメーター

例

$sf.ext.supports()

例

$sf.ext.geom()

例

スクロール位置の例

$sf.ext.expand({params})

パラメーター

例

$sf.ext.collapse()

例

$sf.ext.status()

例

その他のリソース