ニコニ広告情報を取得する

編集
この機能は実験的な機能であり、将来仕様が変更される可能性があります。予めご了承ください。

概要

ニコニ広告情報を取得します。

なにができるのか

次の3種類の取得方法を提供しています。

  • ニコニ広告ポイント取得
  • ニコニ広告履歴取得
  • ニコニ広告貢献度ランキング取得

利用想定／利用例

この機能は、以下のような使い方を想定しています。

  • ゲームが広告されている間だけ、特別な部屋に入室できる
  • 広告履歴をもとに、ゲームを広告してくれたユーザーの名前を表示してお礼を述べるシーンを作る

利用方法

本機能は次の方法で利用できます。

方法場所
RPGアツマール公式プラグインGithub
ゲームAPI以下の「APIでの利用方法」を参考に、直接APIを呼び出してください

公式プラグインの利用方法

公式プラグインで外部リンクを設置するには以下のようにします。

  1. プロジェクトのプラグインフォルダに AtsumaruNiconicoukokuExperimental.js を右クリックし「保存」して設置
  2. プロジェクトのプラグイン設定で AtsumaruNiconicoukokuExperimental プラグインをONにする。

ニコニ広告ポイント取得

  • このゲームに対して、合計何ポイント広告されたかを取得できます。
  • アクティブポイントとは、広告期間以内の広告の合計ポイントです。
  • トータルポイントとは、広告期間が終了したものも含めたすべての広告の合計ポイントです。
  • このAPIはAPIの呼び出し回数制限の対象です。
  1. プラグイン設定画面でプラグインパラメータ「アクティブポイント」「トータルポイント」「エラーメッセージ」にそれぞれの結果を代入する変数を設定します。
  2. プラグインコマンドは次のいずれかのように指定します。（どちらでも動作は同じです）
GetNicoadPoints
ニコニ広告ポイント取得

APIでの利用方法

ニコニ広告ポイント取得

メソッドwindow.RPGAtsumaru.experimental.nicoad.getPoints()
説明このゲームに対して、合計何ポイント広告されたかを取得できます
引数なし
戻り値Promise<NicoadPoints>
制限このAPIはAPIの呼び出し回数制限の対象です
リリース日2019/07/22
更新日2019/07/22
戻り値の型 NicoadPoints について

戻り値で取得できる NicoadPoints は以下のような型です。

interface NicoadPoints {
  activePoint: number;
  totalPoint: number;
}

プロパティの内容は次のようになっています。

プロパティ名型内容
activePointnumberアクティブポイント：広告期間以内の広告の合計ポイント
totalPointnumberトータルポイント：広告期間が終了したものも含めたすべての広告の合計ポイント
戻り値の例
// window.RPGAtsumaru.experimental.nicoad.getPoints().then(function(v) { console.log(v) }) を実行
{
  activePoint: 3000,
  totalPoint: 10000
}
起こりうるエラーの種類
名前説明
INTERNAL_SERVER_ERRORRPGアツマールもしくはニコニ広告のサービス側で何らかの問題が発生しているか、または通信に失敗した（※ユーザーが広告ブロックしている場合も含む）
API_CALL_LIMIT_EXCEEDED短時間にゲームAPIを利用しすぎて、一時的に利用を制限されている

ニコニ広告履歴取得

メソッドwindow.RPGAtsumaru.experimental.nicoad.getHistories()
説明このゲームに対してのニコニ広告の履歴を、最新のものから順に最大30件まで取得します
引数なし
戻り値Promise<NicoadHistories>
制限このAPIはAPIの呼び出し回数制限の対象です
リリース日2019/07/22
更新日2019/07/22
戻り値の型 NicoadHistories について

戻り値で取得できる NicoadHistories は以下のような型です。

interface NicoadHistories {
  remainingCount: number;
  serverTime: number;
  histories: {
    advertiserName: string;
    nicoadId: number;
    adPoint: number;
    contribution: number;
    startedAt: number;
    endedAt: number;
  }[];
}

プロパティの内容は次のようになっています。

プロパティ名型内容
remainingCountnumber今回取得した広告履歴の他に、あと何件広告されたか
serverTimenumberサーバー時刻
historiesarray広告履歴
histories.lengthnumber今回取得した広告履歴の件数
histories[n].advertiserNamestringn+1番目の広告の広告者名
histories[n].nicoadIdnumbern+1番目の広告の広告ID
histories[n].adPointnumbern+1番目の広告のポイント
histories[n].contributionnumbern+1番目の広告の貢献度
histories[n].startedAtnumbern+1番目の広告の掲載開始時間
histories[n].endedAtnumbern+1番目の広告の掲載終了時間
戻り値の例
// window.RPGAtsumaru.experimental.nicoad.getHistories().then(function(v) { console.log(v) }) を実行
{
  remainingCount: 0,
  serverTime: 1534570000,
  histories: [
    {
      advertiserName: "アツマライオン",
      nicoadId: 1234567,
      adPoint: 1000,
      contribution: 3000,
      startedAt: 1534567890,
      endedAt: 1534654290,
    },
    {
      advertiserName: "RPGアツマール開発チーム",
      nicoadId: 1234560,
      adPoint: 10000,
      contribution: 30000,
      startedAt: 1534517890,
      endedAt: 1534604290,
    }
  ]
}
起こりうるエラーの種類
名前説明
INTERNAL_SERVER_ERRORRPGアツマールもしくはニコニ広告のサービス側で何らかの問題が発生しているか、または通信に失敗した（※ユーザーが広告ブロックしている場合も含む）
API_CALL_LIMIT_EXCEEDED短時間にゲームAPIを利用しすぎて、一時的に利用を制限されている

ニコニ広告貢献度ランキング取得

メソッドwindow.RPGAtsumaru.experimental.nicoad.getRanking()
説明このゲームに対してのニコニ広告の貢献度ランキングを、最大30位まで取得します
引数なし
戻り値Promise<NicoadRanking>
制限このAPIはAPIの呼び出し回数制限の対象です
リリース日2019/07/22
更新日2019/07/22
戻り値の型 NicoadRanking について

戻り値で取得できる NicoadRanking は以下のような型です。

type NicoadRanking = {
  advertiserName: string;
  totalContribution: number;
  rank: number;
}[]

プロパティの内容は次のようになっています。

プロパティ名型内容
(this)array広告貢献度ランキング
lengthnumber広告貢献度ランキングの件数（※同着の場合両方含まれるため、31件以上の可能性あり）
[n].advertiserNamestringn+1番目のランキングの広告者名
[n].totalContributionnumbern+1番目のランキングの貢献度
[n].ranknumbern+1番目のランキングの順位
戻り値の例
// window.RPGAtsumaru.experimental.nicoad.getRanking().then(function(v) { console.log(v) }) を実行
[
  {
    advertiserName: "RPGアツマール開発チーム",
    totalContribution: 30000,
    rank: 1
  },
  {
    advertiserName: "アツマライオン",
    totalContribution: 3000,
    rank: 2
  }
]
起こりうるエラーの種類
名前説明
INTERNAL_SERVER_ERRORRPGアツマールもしくはニコニ広告のサービス側で何らかの問題が発生しているか、または通信に失敗した（※ユーザーが広告ブロックしている場合も含む）
API_CALL_LIMIT_EXCEEDED短時間にゲームAPIを利用しすぎて、一時的に利用を制限されている