Cocos2d-x Plugin Getting Started / バナー広告

はじめに

本マニュアルはcocos2d-xでの開発に必要な環境がインストールされていることを前提としています。

platform	version
Cocos2d-x	3.17(動作確認済)
iOS	10.0+
Android	5.0+

導入の流れ

1. SDKをダウンロードします
   ↓
2. iOS用SDKをプロジェクトに追加します
   ↓
3. Android用SDKをプロジェクトに追加します
   ↓
4. iOS用frameworkを追加します
   ↓
5. AndroidManifest.xmlの設定を行います
   ↓
6. Google Play Servicesの設定を行います
   ↓
7. 例を参考に広告表示の実装を行います

1. SDKをダウンロードする

こちらからダウンロードしてください。

iOS SDK ダウンロード (opens new window)
(Downloads > ADG.xcframework.zip )

Android SDK ダウンロード (opens new window)
(Downloads > adg-x.x.x.aar )

Cocos2d-x Plugin ダウンロード (opens new window)
(Downloads > ADG-Cocos2d-x.zip )

2. iOS用SDKをプロジェクトに追加する

アプリケーションのプロジェクトフォルダをAPPと略します。

cocos2d-xのルート/projects/アプリ名

1. SDKのADG_Cocos2dxPlugin/ios/Classesフォルダ内の二つのファイルをApp/Classesフォルダに配置してください。

• ADGConnectionForIOS.h
• ADGConnectionForIOS.mm

2. SDKのios/wrapperフォルダをAPP/proj.ios_mac配下に配置してください。
   下記3ファイルがあります。

• ADGConnectionObjC.h
• ADGMessage.h
• libADGCocos2d-xX.X.X.a (X.X.Xはバージョン番号）

3. SDKのADG_iOSSDKフォルダ内のADG.xcframeworkをAPP/proj.ios（3.0以降ではAPP/proj.ios_macフォルダ）配下に配置してください。

すべてXcode上でプロジェクトナビゲータの任意の場所にドラッグ&ドロップするか、右クリック > Add Files to ... を選択し、"Copy items if needed"にチェックがついていることを確認して、Finishを押し、追加を行ってください。
詳しくはiOS SDK Getting Started / バナー広告をご確認ください。

3. Android用SDKをプロジェクトに追加する

1. SDKのADG_Cocos2dxPlugin/android/Classesフォルダ内の二つのファイルをAPP/Classesフォルダに配置してください。

• ADGConnectionForAndroid.h
• ADGConnectionForAndroid.cpp

2. SDKのADG_Cocos2dxPlugin/android/libsフォルダ内のadgcocos2dx-x.x.x.aarをAPP/proj.android/app/libsフォルダに配置してください。

※ x.x.xにはcocos2d-xプラグインのバージョン番号が入ります。
※ libsフォルダがない場合はlibsフォルダを作った上で配置してください。

3. ADG_AndroidSDKフォルダの中のadg-x.x.x.aarをAPP/proj.android/app/libsに配置してください。

※ x.×.xにはAndroid向けSDKのバージョン番号が入ります。

4. APP/proj.android/app/jniフォルダのAndroid.mkのLOCAL_SRC_FILES :=に以下を指定してください。

$(LOCAL_PATH)/../../../Classes/ADGConnectionForAndroid.cpp

※ 改行に注意してください。

4. iOS用frameworkの追加する

Xcodeにて以下のフレームワークをプロジェクトに追加する。

• SystemConfiguration.framework
• CoreTelephony.framework
• CoreLocation.framework
• AVFoundation.framework
• CoreMedia.framework
• MediaPlayer.framework
• SafariServices.framework
• WebKit.framework
• AdSupport.framework (※)

(※)はOptionalで追加

※FrameworkによってはCocos2d-xでの書き出し時に追加済みのものもあります。

5. AndroidManifestを修正する

APP/proj.androidフォルダのAndroidManifest.xmlで権限の追加を行ってください。

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET"/>

6. Google Play Servicesを設定する

本SDKでは提携DSPの追跡型広告を表示するためGoogle Advertising IDを使用します。
Google Advertising IDを利用するにはAndroid Studio上でのGoogle Play Servicesの導入が必須となります。

導入方法はこちらからご確認ください。
Getting Started / バナー広告

7. 広告表示を実装する

iOS

ADGConnectionForIOS.hをincludeします。

#include "ADGConnectionForIOS.h"

initADGメソッドで広告を表示します。
一度呼び出せば全画面共通で広告が表示されます。

ADGConnectionForIOS::initADG((char*)"48547" , (char*)"SP", 0, 0 , NULL);

initADGメソッドの引数は以下の5つです。

• 広告枠ID：48547を指定すると広告の掲載イメージを確認できます（48547のままリリースしないようご注意ください）
• 広告サイズ：SP:320×50、LARGE：320x100、RECT：300x250、TABLET：728×90
• x座標（左上基準/単位はiOSにおける座標系に従います）
• y座標（左上基準/単位はiOSにおける座標系に従います）
• イベント受け取りメソッド

イベント受け取りメソッドは、イベント受け取りが不要であればNULLを指定します（詳細は後述）。

枠サイズを指定する場合

枠サイズを指定する場合はinitADGWithWHメソッドを使用します。

ADGConnectionForIOS::initADGWithWH((char*)"48547" , (char*)"FREE", 0, 0 , 57 ,  57 , NULL);

initADGWithWHメソッドの引数は以下の7つです。

• 広告枠ID
• 広告サイズ：必ずFREEを指定してください
• x座標（左上基準/単位はiOSにおける座標系に従います）
• y座標（左上基準/単位はiOSにおける座標系に従います）
• 横幅
• 縦幅
• イベント受け取りメソッド

広告の表示倍率を変更する場合

広告の表示倍率を変更する場合はinitADGWithScaleを使用します。
倍率は1.0が等倍（100%）となります。

ADGConnectionForIOS::initADGWithScale((char*)"48547" , (char*)"FREE", 0, 0 , 480 , 75 , 1.5 ,  receiveAdMessage);

initADGWithScaleメソッドの引数は以下の8つです。

• 広告枠ID
• 広告サイズ：必ずFREEを指定してください
• x座標（左上基準/単位はiOSにおける座標系に従います）
• y座標（左上基準/単位はiOSにおける座標系に従います）
• 横幅
• 縦幅
• 表示倍率
• イベント受け取りメソッド

バックグラウンドからの復帰時

バックグラウンドからの復帰時にshowADGメソッドを呼び出します。

void AppDelegate::applicationWillEnterForeground() {

  〜省略〜

  ADGConnectionForIOS::showADG();
}

その他のメソッド

• loadADG：広告ロード

  ADGConnectionForIOS::loadADG();
  

• hideADG：非表示

  ADGConnectionForIOS::hideADG();
  

• showADG：非表示を解除

  ADGConnectionForIOS::showADG();
  

• changeLocationADG：位置変更

  //引数はx座標 , y座標
  ADGConnectionForIOS::changeLocationADG(50 , 100);
  

• changeLocationEasyADG：簡易位置変更
  ※「現在の画面向き」での指定のため、回転の際に自動で調整はされません。

  //引数は横方向（LEFT / CENTER / RIGHT） , 縦方向（TOP / CENTER / BOTTOM）
  changeLocationEasyADG((char*)"RIGHT", (char*)"CENTER");
  

• moveDefaultLocationADG：初期位置に戻す

  ADGConnectionForIOS::moveDefaultLocationADG();
  

• finishADG：表示終了

  ADGConnectionForIOS::finishADG();
  

イベント

イベントを受け取る場合はさらに以下の手順も必要となります。

• receiveAdMessageを定義する。

  void receiveAdMessage(const char* msg , const char* adid);
  

• receiveAdMessageの処理を記述する。

  void receiveAdMessage(const char* msg , const char* adid){
    //CCLog("msg:%s adid:%s" , msg , adid);
  }
  

adidには枠IDが、msgにはイベント内容が格納されます。

イベント内容は以下の通りです。

• ADGReceiveAd：広告受信時
• ADGFailedToReceiveAd：広告受信失敗時
• ADGOpenUrl：広告タップでのURL遷移時
• ADGNeedConnection：ネットワーク不通検知時
• ADGExceedErrorLimit：エラー多発時

ADGOpenUrlは一部SDK連携や広告フォーマットによっては、呼び出せない場合もあるため、
すべてのケースにおける広告タップ時のコールバックを保証するものではありません。

広告表示メソッドの最終引数にreceiveAdMessageを指定する。

ADGConnectionForIOS::initADG((char*)"48547" , (char*)"SP", 0, 0 , receiveAdMessage);

Android

ADGConnectionForAndroid.hをincludeします。

#include "ADGConnectionForAndroid.h"

initADGメソッドで広告を表示します。
一度呼び出せば全画面共通で広告が表示されます。

ADGConnectionForAndroid::initADG((char*)"48547" , (char*)"SP" , (char*)"CENTER" , (char*)"TOP");

引数は以下の通りです。

• 広告枠ID：48547を指定すると広告の掲載イメージを確認できます（48547のままリリースしないようご注意ください）
• 広告サイズ：SP:320×50、LARGE：320x100、RECT：300x250、TABLET：728×90
• 横位置：LEFT、CENTER、RIGHT
• 縦位置：TOP、BOTTOM

枠サイズを指定する場合

枠サイズを指定する場合はinitADGWithWHメソッドを使用します。

ADGConnectionForAndroid::initADGWithWH((char*)"48547" , (char*)"FREE" , (char*)"CENTER" , (char*)"TOP" , 57 , 57);

引数は以下の6つとなります。

• 枠ID
• 広告サイズ：必ずFREEを指定してください
• 横位置
• 縦位置
• 横幅
• 縦幅

広告の表示倍率を変更する場合

広告の表示倍率を変更する場合はinitADGWithScaleを使用します。
倍率は1.0が等倍（100%）となります。

ADGConnectionForAndroid::initADGWithScale((char*)"48547" , (char*)"FREE" , (char*)"CENTER" , (char*)"TOP" , 480 , 75 , 1.5);

init以外のメソッド

• loadADG：広告ロード

  ADGConnectionForAndroid::loadADG();
  

• hideADG：非表示

  ADGConnectionForAndroid::hideADG();
  

• showADG：非表示を解除

  ADGConnectionForAndroid::showADG();
  

• changeLocationADG：位置変更

  //引数は横位置 , 縦位置
  ADGConnectionForAndroid::changeLocationADG((char*)"LEFT" , (char*)"BOTTOM");
  

• moveDefaultLocationADG：初期位置に戻す

  ADGConnectionForAndroid::moveDefaultLocationADG();
  

• changeMarginADG：余白変更

  // 引数は左、上、右、下のpx値となります。
  ADGConnectionForAndroid::changeMarginADG(10 , 10 , 0 , 0);
  

• finishADG：表示終了

  ADGConnectionForAndroid::finishADG();
  

イベント

イベントを受け取る場合はさらに以下の手順も必要となります。

以下のincludeを追加します。

#include "ADGConnectionForAndroid.h"
#include "platform/android/jni/JniHelper.h"
#include <jni.h>

以下のコードを追加します。

extern "C" {
  JNIEXPORT void Java_com_socdm_d_adgeneration_plugin_cocos2dx_adgni_ADGNICocos2dx_receiveAdMessage(JNIEnv* env, jobject obj,jstring msg,jstring adid)
  {
    //msgがイベント内容、adidが枠ID
    const char *retmsg = env->GetStringUTFChars(msg, 0);
    const char *retid = env->GetStringUTFChars(adid, 0);

    //ここに処理を記述する。

    //解放
    env->ReleaseStringUTFChars(msg, retmsg);
    env->ReleaseStringUTFChars(adid, retid);
  }
}

イベント内容は以下の通りです。

• ADGReceiveAd：広告受信時
• ADGFailedToReceiveAd：広告受信失敗時
• ADGOpenUrl：広告タップでのURL遷移時
• ADGNeedConnection：ネットワーク不通検知時
• ADGExceedErrorLimit：エラー多発時

ADGOpenUrlは一部SDK連携や広告フォーマットによっては、呼び出せない場合もあるため、
すべてのケースにおける広告タップ時のコールバックを保証するものではありません。

複数広告の設置について

現在、一画面で複数広告を扱うメソッドは用意されていません。

そのため、一画面に複数の広告を設置したい場合は以下の手順で対応をお願いいたします。

• Classesフォルダの以下4ファイルを複製する。
  • ADGConnectionForAndroid.h
  • ADGConnectionForAndroid.cpp
  • ADGConnectionForIOS.h
  • ADGConnectionForIOS.mm
• 複製したファイルの名前を変える（例：ADGConnectionForIOS2.h）
• ファイルを開き、コード内におけるファイル名と同様の箇所を一括置換する
  （例：ADGConnetcionForIOSをADGConnectionForIOS2で一括置換）
• Xcodeでの追加とAndroid.mkへの追加を行う。

これで変更後のファイル名で各メソッドにアクセスできます。

ADGConnectionForIOS2::showADG();

iOSとAndroidの併用例について

iOS向けのコードとAndroid向けのコードの同一ファイルへの併記はプリプロセッサの使用を想定しています。

#if (CC_TARGET_PLATFORM == CC_PLATFORM_ANDROID)
ADGConnectionForAndroid::initADG((char*)"48547" , (char*)"SP" , (char*)"LEFT" , (char*)"TOP");
#elif (CC_TARGET_PLATFORM == CC_PLATFORM_IOS)
ADGConnectionForIOS::initADG((char*)"48547" , (char*)"SP", 0, 0 , receiveAdMessage);
#endif