facebook-ruby-ads-sdkの読み方
facebook-ads-sdk
facebook-ads-sdkとはfacebook広告に関するAPI（マーケティングAPI）を扱うためのSDKである。マーケティングAPIはjsonのやり取りで定義されているが、facebook-ads-sdkを用いればより簡単に利用することができる。ただし、APIそのものと違い、自然言語で書かれた解説が少ない。少なくともRubyのSDKに関しては少なかった。よって本記事ではfacebook-ads-sdk（Ruby版）のソースコードからその仕様を理解するための方法について説明する。仕様そのものについてはそこまでちゃんと説明しません。
説明書を読む
- SDK - マーケティングAPI - ドキュメンテーション - 開発者向けFacebook
- facebook-ruby-ads-sdk
上は日本語で書かれたマーケティングAPIのSDKに関する説明書、下はそのRuby版のGithub。上のサイトの「ダウンロードする」リンクでRuby SDKを選ぶと下のGithubに飛ばされる。ただし、使いたいだけならソースコードからインストールする必要はなく、gem install facebookads、gemfileならgem 'facebookads'で良い。
上の日本語ページにはSDKの使い方はほとんど書いておらず、詳しい説明はGitHubのreadme.mdにある。アクセストークン云々のようなAPIを使うための初期設定についてはここに書いてあることをそのまま実行すれば問題ない。そもそものアクセストークンの取り方についてはこの辺をリンク先含めて丹念に読み込んでください。そもそもアクセストークンとはいったい何なのか、という場合はマーケティングAPIではなく普通のFacebook APIを使う練習などを先にやることをお勧めします。
GitHubのreadmeに話を戻すと、初期設定の下に書いてあるサンプルコードを利用すればある程度の操作は可能である。広告は上から「広告アカウント」「キャンペーン」「広告セット」「広告」の順に木構造になっているが、既に存在するこれらの一つ一つの要素について、名前をとってきたり削除したりといったことはできるようになる。しかし、実用上でマーケティングAPIを使うのであれば、用意したテキストや画像から自動で広告を生成・操作するといったことが主になる。これらについてはreadmeの記述だけでは対応することはできず、しかしこのSDKに関して用意されている自然言語の文書はこのreadmeのみである。
サンプルプログラムを読む
幸いなことに、GitHubのexamplesフォルダに使用例となるいくらかのスクリプトが置いてある。が、残念ながらソースコードの処理に関するコメントはついていない。引数をハッシュで渡すタイプのライブラリ故なんとなく読めるようになってはいるが、正確な内容を理解するためにはGitHubから直接ではなくいったんローカルにクローンしてから読んだ方が良い。「basic.rb」「create_complete_campeign.rb」「dynamic_ads/create_dynamic_ads_flight.rb」の三つを読めば大まかな流れはつかめる。その後に必要であればその他の使いそうなファイルを読むと良い。
しかし、最も詳しく書かれているサンプルが「create_complete_campeign.rb」「dynamic_ads/create_dynamic_ads_flight.rb」の二つであるが、この二つに書かれている内容だけではFacebookの広告ページGUIから操作するような豊富なデザインの広告をすべて利用するための方法がわからないことはすぐに理解できる。そもそもハッシュの引数にとられている文字列は何が利用可能なのかもサンプルに出てきているもの以外はわからない。よって、結局はSDKを実用レベルで利用するにはライブラリの中身を直接読む必要がある、ということになる。
ライブラリの中身を読む
この手の未知の巨大プログラム（といっても今回はそこまで大きなライブラリというわけでもない）を読んでいく場合は、メインとなる処理のメソッド名をgrepやエディタの全文検索でたどりながら中身に立ち入っていく、という流れが一般的である。原始的なテキストエディタしか利用できない環境ではgrepコマンドでたどっていく他ないが、Visual Studio Code や Atom のような、フォルダ内のファイルを含めて全文検索が可能なテキストエディタが利用可能であれば、より効率的に処理をたどることが可能となる。今回は、アプリケーションではなくライブラリのため「メインとなる処理」がやや掴みにくいが、せっかくサンプルプログラムがあるので、「create_complete_campeign.rb」あたりを上から順に読みつつ、そのメソッド名で全文検索して定義を当たる、という流れがよさそうである。
例えば、以下の処理について
adset = ad_account.adsets.create({
name: 'Test Ad Set',
campaign_id: campaign.id,
bid_amount: 1000,
billing_event: 'LINK_CLICKS',
daily_budget: 15000,
targeting: {
age_max: 65,
age_min: 18,
geo_locations: {
countries: [
"HK"
]
},
publisher_platforms: [
"facebook",
],
facebook_positions: [
"feed",
],
instagram_positions: [
"stream",
],
device_platforms: [
"mobile",
"desktop",
],
}
})
この場合、まずはadsetあたりで全文検索をすることになる。と、いろいろ出てくるが、ad_set.rbなるファイルにAdSetクラスがあることがわかる。createはrubyの命名慣行から推測するに、コンストラクタ的ななにかである可能性が高いので、AdSetクラスの中身を覗くと、様々な列挙型定義の後に、fieldが大量に並んでいるのがわかる。サンプルプログラムのコードと見比べると、name, campaign_id, billing_event, targeting など、呼び出し時のハッシュのキーとして指定されているフィールドが、このフィールド一覧にすべて存在することがわかる。ただし、targetingフィールドのみ呼び出しで入れ子になっているのでこれを確認すると、フィールドの型として'Targeting'とあるのがわかる。よって再びTargetingで全文検索を行うと、やはり「targeting.rb」なるファイルがが見つかり、そこにクラスの定義と大量のfieldが並んでいる。そしてその中には age_max, geo_locations, publisher_platforms といったサンプルプログラムのフィールドが同じように見つかる。
以上から考えるに、クラスとそのフィールドをたどっていくことで、指定したい要素についてはすべて設定可能であろうことが推測される。あとはこのプログラムの構造に従って、createの引数として初期設定をハッシュで与えたり、getでとってきたもののうち対象となるフィールドの値を書き換えたりすれば、望み通りに広告の情報を操作することが可能であるということになる。
