Skip to main content
広告ユニットAPIを使うと、サーバーから広告ユニットを作成・管理できます。APIで作成したユニットはすぐにコンソールに表示されます。ユニットIDは、SDK連携と広告商品APIのクリエイティブセットに使います。 APIは、コンソールの広告ユニットと同じデータを扱います。コンソールで作成したユニットもAPIで取得・更新できます。

事前準備

  • ad-unit:readとad-unit:writeのスコープを持つAPIキーが必要です。この2つのスコープは、コンソールの [設定] > [連携] メニューでは選択できません。Adropにご依頼いただければ、スコープを含むキーを発行します。アプリAPIと広告商品APIのスコープも、同じキーにあわせて含めることができます。
  • 2つのスコープは別々に確認されます。ad-unit:writeだけのキーは、取得(GET)リクエストで403を受け取ります。作成・更新のレスポンスにはユニット全体が含まれますが、ユニットを別途取得するにはad-unit:readも必要です。
  • ユニットを作成するアプリのIDは、アプリAPIで取得します。
APIはサーバーからのみ呼び出してください。APIキーをアプリやウェブページに含めないでください。

基本情報

429を受け取ったら、Retry-Afterヘッダーの秒数だけ待ってから再送信してください。サーバーが混雑しているときは、リクエストを1件ずつ送っても429を受け取ることがあります。

エンドポイント

パスはBase URLを基準とします。

ユニットの作成

新しい広告ユニットを作成します。

リクエスト

ad-unit:writeスコープが必要です。

リクエスト本文

  • 省略した値は、コンソールのユニット作成画面と同じく、フォーマットごとのデフォルト値で設定されます。
  • 設定をオンにして、その設定に付随する値を送らなかった場合は、コンソールと同じデフォルト値が入ります。たとえばcarouselActivatedをオンにすると、carouselShowIndicatorとcarouselRollingIntervalがデフォルト値で設定されます。
  • Webアプリには、バナーとネイティブのユニットのみ作成できます。
  • レスポンスにのみあるフィールド(_id、connected、archived、createdAt、updatedAt)と、ここにないフィールドを送ると、400 VALIDATION_FAILEDを返します。

リクエスト例

レスポンス例

201で、作成したユニットをユニットオブジェクトとして返します。
作成リクエストは冪等(idempotent)ではありません。レスポンスを受け取れずに同じリクエストを再送信すると、ユニットが重複して作成されることがあります。再送信する前に、ユニット一覧でユニットが作成されたか確認してください。

エラー

  • 400 AD_UNIT_VALIDATION_FAILED: サイズ、フォーマット別の設定の範囲、設定間の条件などのユニットのルールに違反しました。
  • 400 AD_UNIT_NATIVE_SLOTS_NOT_ACCEPTABLE: nativeSlotsがルールに合っていません。
  • 404 PROJECT_APP_NOT_FOUND: appがこのプロジェクトのアプリではありません。

ユニットオブジェクト

取得、作成、更新のエンドポイントは、次の形式でユニットを返します。 featuresは、保存されていない設定をデフォルト値で埋めて返すことはありません。

フォーマットとサイズ

formatには、次の値を大文字と小文字も含めて正確に指定します。
  • バナー、ネイティブ、ポップアップでは、プリセット以外のサイズを直接指定できます。幅と高さはそれぞれ1〜10,000の整数で、ポップアップは幅:高さの比率が2:3〜3:2である必要があります。
  • 動画サイズ(320x180、180x320)を使う場合は、video.dimensionsに同じ比率(16:9、9:16)を指定します。
  • リワードユニットのクリエイティブは、常に9:16の動画です。
各フォーマットの特徴は広告ユニットフォーマットを参照してください。

フォーマット別の設定

featuresには、そのフォーマットで使う設定だけを入れられます。ほかのフォーマットの設定を入れると400を返します。数値はJSONの数値で送り("1000"のような文字列は受け付けません)、時間の値の単位はミリ秒です。

すべてのフォーマット

インタースティシャル、リワード、スプラッシュでは、動画の設定(videoSupported、videoController、videoSkipDelayMs)は常にオフです。

バナー

ネイティブ

ポップアップ(下部・中央)

インタースティシャル

スプラッシュ

リワードでは、すべてのフォーマットに共通の設定のみを使います。

設定の条件

  • テンプレートのみ(useTemplate)は、プリセットサイズを使い、動画のないバナーでのみオンにできます。
  • canSupportThemeDarkは、テンプレートのみをオンにしていないバナー、画像・動画のあるネイティブ、ポップアップ、スプラッシュでのみオンにできます。
  • 画像・動画のないネイティブでは、広告マークを表示(useWatermark)、CTAボタン、動画素材を受付をオンにできません。
  • 範囲は、その設定がオンの場合にのみ確認します。たとえばcarouselRollingIntervalは、carouselActivatedがオンの場合に確認します。

ネイティブのテキストとメディア

  • nativeTextsの項目は、id(英小文字、数字、_)、label、maxLength(0より大きい最大文字数)、optional(任意項目かどうか)で構成されます。最大50個まで入れられます。
  • headline(広告タイトル)とbody(広告説明)は、nativeTextsの1番目か2番目にのみ置けます。
  • nativeSlotsの項目はid、label(任意)、w、hで構成され、画像・動画のあるネイティブでのみ使えます。1番目のメディアのidはm1で、サイズはユニットのsizeと同じである必要があります。最大3個まで入れられ、メディアが1つだけの場合は[]として保存されます。
  • idは、nativeTextsとnativeSlotsのすべてを通して重複できません。
nativeSlotsのルールに違反すると400 AD_UNIT_NATIVE_SLOTS_NOT_ACCEPTABLEを返し、detail.reasonで理由を知らせます。複数メディアについてはネイティブの複数メディアを参照してください。

ユニット一覧の取得

プロジェクトのユニットを新しい順に、ページ単位で返します。デフォルトでは、削除されたユニットは含まれません。

リクエスト

ad-unit:readスコープが必要です。

クエリパラメーター

リクエスト例

レスポンス例

200で、items(ユニットの一覧)とnext(次のページのカーソル)を返します。nextがなければ最後のページです。
並び順はおおむね作成の新しい順ですが、古いユニットは順序が異なる場合があります。順序に頼らず、nextで続きを読み込んでください。

ユニットの取得

1つのユニットを返します。削除されたユニットもIDで取得でき、その場合archivedはtrueです。

リクエスト

ad-unit:readスコープが必要です。

リクエスト例

レスポンス

200でユニットオブジェクトを返します。

エラー

  • 404 AD_UNIT_NOT_FOUND: ユニットが存在しないか、ほかのプロジェクトのユニットです。

ユニットの更新

送ったフィールドだけを変更します。

リクエスト

ad-unit:writeスコープが必要です。リクエスト本文は、ユニットの作成のフィールドからappを除いたものと同じです。ユニットのアプリは変更できません。

クエリパラメーター

変更のされ方

  • 送らなかったフィールドはそのままです。空の本文{}を送っても何も変わりません。
  • featuresは、送った設定だけが変わり、残りの設定はそのままです。ただし、carouselActivated、videoSupported、videoControllerをオン・オフすると、一緒に送らなかった従属する設定(carouselShowIndicator、carouselRollingInterval、videoController、videoSkipDelayMs)は、オンにしたときは既定値に、オフにしたときはオフの値に変わります。
  • nullを送れるのは、desc(説明の削除)、size(画像・動画のないネイティブへの変更)、video(動画サイズの解除)、features.carouselCountLimit(ポップアップのカルーセル数の制限をオフにする)だけです。
  • フォーマットを変更するときに、現在のサイズが新しいフォーマットのプリセットでない場合は、sizeも一緒に送る必要があります。新しいフォーマットで使わない設定は削除され、新しいフォーマットの設定はデフォルト値で設定されます。
  • 削除されたユニットは更新できません(409 AD_UNIT_ARCHIVED)。

変更できないフィールド

SDKから広告がリクエストされたことのあるユニット(connected: true)と、広告商品のクリエイティブセットに含まれているユニットは、format、size、video、nativeSlotsのidを変更できません(409 AD_UNIT_FIELD_LOCKED)。名前、説明、その他の設定は変更できます。

広告商品への影響

広告商品に含まれているユニットのuseTemplate、useWatermark、featuresを変更すると、クリエイティブセットの基準に合わなくなることがあります。その場合、そのユニットはその商品で 修正必要 ステータス(fixRequired)になり、広告が配信されません。詳しくは広告商品APIのクリエイティブセットを参照してください。 このユニットを使う商品が多すぎて一度に再調整できない場合は、409 AD_UNIT_RECONCILE_LIMIT_EXCEEDEDを返し、何も変更しません。detail.limitには超えた上限の名前が、detail.maxにはその上限値が入っています。
ユニットを取得したレスポンスから、レスポンスにのみあるフィールド(_id、app、connected、archived、createdAt、updatedAt)を除いてそのまま送ると、何も変わりません。かなり前にコンソールで作成したユニットは、featuresの数値が文字列(例:"1000")で保存されていることがあるため、送り直すときは数値に変換して送ってください。

リクエスト例

レスポンス

200で、更新したユニットオブジェクトを返します。

エラー

  • 404 AD_UNIT_NOT_FOUND: ユニットが存在しないか、ほかのプロジェクトのユニットです。
  • 409 AD_UNIT_ARCHIVED: 削除されたユニットです。
  • 409 AD_UNIT_CONFLICT: ifUpdatedAtがユニットのupdatedAtと異なります。ユニットを取得し直してから更新してください。
  • 409 AD_UNIT_FIELD_LOCKED: 変更できないフィールドを変更しようとしました。
  • 409 AD_UNIT_RECONCILE_LIMIT_EXCEEDED: このユニットを使う商品が多すぎます。

ユニットの削除

ユニットを削除します。削除したユニットは元に戻せません。

リクエスト

ad-unit:writeスコープが必要です。

リクエスト例

レスポンス例

200で、ユニットIDを返します。
  • 削除したユニットは一覧に表示されなくなりますが、IDでは引き続き取得できます(archived: true)。すでに削除したユニットをもう一度削除しても200を返します。
  • 削除したユニットは、このユニットを使うすべての広告商品のクリエイティブセットから外れます。空になったクリエイティブセットも一緒に削除されるため、ユニットが1つもない商品が残ることがあります。
削除する前に、広告商品APIでこのユニットを使う商品があるか確認してください。商品一覧にはユニットIDが含まれないため、商品ごとに取得してunitGroups[].unitsを確認します。

エラー

  • 404 AD_UNIT_NOT_FOUND: ユニットが存在しないか、ほかのプロジェクトのユニットです。
  • 409 AD_UNIT_RECONCILE_LIMIT_EXCEEDED: このユニットを使う商品が多すぎます。先に商品からこのユニットを外してください。

エラー処理

エラーレスポンス

エラーレスポンスにはstatusCodeが含まれ、下の表でerrorCodeの欄が-ではないエラーにはerrorCodeも含まれます。リクエストのどの部分が誤っているかを知らせるエラーは、detailも一緒に返します。処理はerrorCodeで分け、errorCodeがない場合はstatusCodeで分けてください。
detail.errors[]のpathは誤ったフィールドの位置で、valueは送った値です。detail.errorsには最大100件まで含まれます。リクエスト形式のエラー(VALIDATION_FAILED)にはmessageとerrorフィールドも含まれますが、featuresのエラーはmessageでは1行にまとめられるため、設定ごとのエラーはdetail.errors[]で確認してください。

エラーコード

再送信

  • 書き込みリクエスト(POST、PATCH、DELETE)が502を受け取ったか、レスポンスなしで切断された場合は、リクエストが反映されている可能性があります。再送信する前にユニットを取得して確認してください。作成リクエストは冪等ではないため、そのまま再送信するとユニットが重複して作成されることがあります。
  • ifUpdatedAtを付けた更新リクエストを再送信する場合、前のリクエストが反映されていると409 AD_UNIT_CONFLICTを受け取ることがあります。ユニットを取得し直して確認してください。

上限