広告配信システム アスタ用 iOSモジュール(スモールフロート広告)
Mr6SmallFloatSDK ご利用方法

2015年10月1日
株式会社マルジュ
http://www.astrsk.net/

はじめに

広告配信システム「アスタ」をご利用検討くださいましてありがとうございます。
当ファイルはお手持ちのiOS用プロジェクトで広告を取得して表示できるように、
SDK の組み込みの流れを大まかに説明したものでございます。
断片的でわかりにくいなど、全体的なプログラミングコードを確認したい場合には、
SDK圧縮ファイルに同梱の Mr6SmallFloatSDK-SampleApp XCode プロジェクトをご覧下さい。

本文書の構成


ビルドまでの手順

<共通部分>

プロジェクトのターゲット設定で、「Link Binary With Libraries」の箇所へ
Mr6SmallFloatSDK.framework を Finder からドラッグドロップして追加します。(下図(1) )
ファイルリストの先頭にアイコンが現れますので、必要に応じて分かりやすい箇所へ移動させ下さい。(下図(2))

(Xcode 6.1.1の設定画面です。バージョンによっては多少異なる可能性がございます)

AdSupport.framework を追加します。

広告枠を配置する必要のあるソースコード内で、ヘッダをインポートします。


#import <Mr6SmallFloatSDK/Mr6SmallFloatSDK.h>
        

基本的な配置の処理は以下のようになります。
配置したい画面のUIViewControllerにコードを記述し、self.view で画面のUIViewを参照できるものとします。

Mr6Loader* loader = [[Mr6Loader alloc]init]; // (1)
CGRect frame = CGRectMake(10,10,114,114);
Mr6Spot* spot = [[Mr6Spot alloc]initWithFrame:frame]; // (2)
[spot autorelease]; // (3)
[loader addSpot:spot]; // (4)
[self.view addSubview:spot]; // (5)
[loader startLoadWithMediaCode: @"MyMediaCode"]; // (6)
_loader = loader; // (7)
        
(1) loader (広告の読み込みを管理するクラス) の生成。
(2) spot (個々の広告画像; UIView のサブクラス) の生成。
(3) spot は (4) で loader に retain されますので、非ARC環境の場合は autorelease しておきます。(ARC環境の場合は、この行は必要ありません。)
(4) loader への spot の登録(retain されます)。
(5) 表示させたい場所の view へ 配置。
(6) 広告取得処理開始。@"MyMediaCode"はWebの管理ページで記載されたコードを記述します。
(7) 何らかのインスタンス変数(ここでは _loader )に loader を保存。(後で停止させるため)

(2) から (5) の部分を繰り返す事で、画面の空いたスペースに複数配置できます。(上限20)

1つのloaderインスタンスに複数個のspotをaddSpot:した際には、同じ広告を2つ以上同時取得しないように制御されます。
このため、場合によっては配置したspotのうちのいくつかが空白になるケースがあります。(マッチする広告が不足しているケース等)
(後述のdelegate にて エラー通知されます)
※ これら一連の処理はメインスレッドで行ってください。

広告取得や次の取得のためのタイマーを停止する処理

[loader stop];
// 他の view を上に重ねたり、スクロールさせたりする操作は自動検出されません。
// 不要な通信など処理が発生して欲しくない場合にご利用下さい。
// アプリがバックグラウンドにいる場合や removeFromSuperview などで除去されている時は
// 自動的に検出されるため、この操作をしなくても新たな通信は発生しません。
        
解放処理

[_loader release];
_loader = nil;
// release により、登録した spot は全てremoveSpot:されますが、
// removeFromSuperview は呼ばれません。
// superview が dealloc されるケース以外では、明示的な removeFromSuperview が必要です。

// 個別の spot だけ不要になったとき
[_loader removeSpot:spot];
[spot removeFromSuperview];
        

通信上の制限により、多数の spot を同時に生成し過ぎるとクラッシュする場合があります。
不要になったら解放するか、画面外に隠れているものがあれば再利用してください。


▽ その他、オプションで指定可能な項目
loader.refreshInterval
広告の自動更新の間隔(秒)。1500以下の10以上の値を指定してください。
なおネットワーク状況により、データ受信に時間がかかることがありますので、
いくらかの誤差が発生する場合があります。
loader.delegate
広告の取得やエラーの発生を捕まえるための任意のオブジェクトを指定します。
delegate は loader 側では retain されません。
設定する場合は、通信途中などに release されないようご注意ください。
必ず先に [loader release]、または[loader setDelegate:nil]で、
解放済オブジェクトへのアクセスを防いでください。
loader.userAttributes
広告配信のカテゴリの精度を上げるための追加情報を指定します(任意)
userAttributes(ユーザ属性) について
以下の要領で付加情報を設定します。

loader.userAttributes = @{
    key1 : value1 ,
    key2 : value2 ,  ...
};

現在使用可能な項目は以下のものです。
判定式は、アプリの性格から明らかである場合は 値を直接コーディングしていただいても構いません。
データが不明な時は不正確になる恐れがありますので付加しないでください。

・ pay : 課金可能なら 1 、そうでなければ 0
 判定式 ([SKPaymentQueue canMakePayments]) ? @"1" : @"0"
 ※ 要StoreKit.

・ kids : 未成年であるなら 1 、そうでなければ 0
 判定式  ([[GKLocalPlayer localPlayer]underage]) ? @"1" : @"0" 
 ※ 要GameKit. localPlayer については認証が必要
 ※ アプリのレーティングが17+であれば、判定をスキップしても構いません。

・ sex  : 性別 { 男性: M, 女性 : F, その他: X }
 アプリの性質、会員登録など独自で判定して実装してください。
            
loader.expandBackgroundImage
エキスパンドダイアログが表示されるタイプの広告の際に、ダイアログの枠部分に任意の背景画像を指定できます。
設定する場合は、サイズが312 x 314 pixelsもしくはそれのRetina対応密度の任意のUIImageを指定します。
[loader closeDialog]
開いているエキスパンドダイアログがあれば、強制的にそれを閉じます。
(これはプロパティではなくメソッドとなります)
spot.paperRollupColor
画面の背景がめくれたような視覚効果の色。任意の UIColor のインスタンスを設定可能です。
spot.titleTextColor
テキストの色。任意の UIColor のインスタンスを設定可能です。
spot.titleShadowColor
テキストの陰影の色。任意の UIColor のインスタンスを設定可能です。
▽ loader.delegate にオブジェクトを指定した場合、下記の通知を受取り可能です。

@protocol Mr6LoaderDelegate 

@optional
- (void)loader:(Mr6Loader*)loader didReceiveContentForSpots:(NSArray*)spots; // (1)
- (void)loader:(Mr6Loader*)loader didFailToLoadContentForSpots:(NSArray*)spots; // (2)

- (BOOL)loader:(Mr6Loader*)loader willHandleTapOnSpot:(Mr6Spot*)aSpot; // (3)
- (BOOL)loader:(Mr6Loader*)loader willOpenURL:(NSURL*)url onSpot:(Mr6Spot*)aSpot; // (4)
- (BOOL)loader:(Mr6Loader*)loader willOpenURLAfterOpenDialog:(NSURL*)url onSpot:(Mr6Spot*)aSpot; // (5)

- (void)loader:(Mr6Loader*)loader didOpenDialog:(Mr6Spot*)aSpot; // (6)
- (void)loader:(Mr6Loader*)loader didCloseDialog:(Mr6Spot*)aSpot; // (7)
- (void)loader:(Mr6Loader*)loader didDetectCloseButtonWasTapped:(Mr6Spot*)aSpot; // (8)
- (void)loader:(Mr6Loader*)loader didDetectDialogImageWasTapped:(Mr6Spot*)aSpot; // (9)
@end
        
(1) didReceiveContentForSpots
広告データの受信完了時に通知されます。(NSArray*)spots は、受信に成功したspotの配列になります。
(2) didFailToLoadContentForSpots
広告データの受信完了と同じタイミングで、もし受信に失敗したspotがあれば通知されます。
(NSArray*)spots は、受信に失敗したspotの配列になります。
(3) willHandleTapOnSpot
spotがタップされ、SDK内部でのクリック時処理が開始される直前に通知されます。
return NO とすると、処理をキャンセルできますが、通常はreturn YESとなるように実装して下さい。
(4) willOpenURL
spotがタップされ、広告先の外部URLを開く直前に通知されます。スモールフロート広告(ノーマル)の場合がこの通知に該当します。(エキスパンド有りの場合は、外部URLではなくダイアログが開くため)
return NO とすると、処理をキャンセルできますが、通常はreturn YESとなるように実装して下さい。
(5) willOpenURLAfterOpenDialog
エキスパンドダイアログの広告画像部分がタップされ、広告先の外部URLを開く直前に通知されます。
引数のonSpot:は、このダイアログを開く際にタップしていたspotがはいります。
return NO とすると、処理をキャンセルできますが、通常はreturn YESとなるように実装して下さい。
(6) didOpenDialog
エキスパンドダイアログが開いた直後に通知されます。
(7) didCloseDialog
エキスパンドダイアログが閉じられた直後に通知されます。
(8) didDetectCloseButtonWasTapped
エキスパンドダイアログのCloseボタンがタップされた直後に通知されます。
(9) didDetectDialogImageWasTapped
エキスパンドダイアログの広告画像部分がタップされた直後に通知されます。

< コンバージョン記録 >

アスタで広告を出稿し集客を行う、またはその可能性が近々ある方向けの機能です。
アスタの広告クリック後にアプリを起動したユーザ数をカウントし、
お支払い額とインストール数を比較し、広告効果測定をすることができます。

[ SDK内 API 方式 ]

内蔵のアプリ間通信機能で成果達成(インストール完了)を通知します
Webから来たユーザに対してはこちらの方法では記録できませんのでご注意ください。(詳細後述)

実装手順
以下のコードをアプリの applicationDidFinishLaunching{} 内に記述してください

NSString* promotionKey = @"PROMOTION_KEY"; // (1)
NSTimeInterval sec = 20; // (2)
[Mr6CVReporter sendUntilSuccess:promotionKey retryInterval:sec];
            
(1) アプリを区別するためのコードを記載します。コードは管理ページからご確認下さい。
(2) 圏外の場合など、通信エラー時に自動再送信するまでの待ち時間を指定します。

通信が発生しますので、起動直後に多数の通信が発生するネットワーク系のアプリなどは、
互いに通信を阻害しないよう、別の箇所に記載いただいても問題ございません。
(実装例は SampleAppDelegate.m をご覧下さい)


[ Webサイト方式 ]

ユーザがWebサイトから来た場合、クリックした履歴はブラウザのCookieにのみ保存されているため、
それを使用するためWebブラウザ(Safari)をアプリ内から起動する必要があります。
(アプリからの場合も一瞬Webを開きますので、この方法で両方に対応できます)
いきなりWebを開くとApple社の審査時にマイナス評価を受ける可能性がありますので扱いにご注意ください。

実装手順

補足の内容(共通)

コンパイル時に「framework Mr6SmallFloatSDK was not found」エラーが出る場合:

アプリケーションのビルド設定 (Build Settings)で
Framework Search Paths に フレームワークを置いたディレクトリが含まれているかご確認下さい。
( $(SRCROOT) はプロジェクトのソースのあるディレクトリに展開されます)

XCode7 以上でビルド時の補足事項 (共通)

本SDKのバージョンv1.0.0 を、XCode 7 以上の環境でお使いの場合は、ビルド時に以下の設定が必要です。
なお、バージョンv1.0.1 以降をお使いの場合は、特に設定は必要ありません。

< Build Settings で Bitcode について設定 >

v1.0.0 のフレームワークにはBitcodeが含まれておりませんので、ビルドターゲットの Build Settings にて
「Enable Bitcode」を No に設定してください。

< App Transport Security の除外ドメインを設定 >

v1.0.0 ではサーバーとの通信を HTTP で行なう仕様となっておりますため、プロジェクトの Info.plist ファイルを編集して
iOS 9以上でアスタのドメイン (astrsk.net) に対しての HTTP 通信を許可してください。


Info.plist の XML を直接編集される場合は、以下の内容を記述してください。

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>astrsk.net</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSIncludesSubdomains</key>
            <true/>
        </dict>
    </dict>
</dict>
        

対応OSバージョン

iOS Deployment Target は iOS 7.0 以上をご指定ください。
Deployment Target が 7.0 未満 4.3以上の場合、framework を組み込んだアプリのビルド自体は出来、
アプリの動作にも支障はありませんが、広告は表示されない仕様となっております。
それ以前のOSはサポート外とさせていただいております。ご了承ください。

更新履歴

v1.0.1  (2015.10.1)
  • 旧バージョン(v1.0.0)のSDKを、XCode7 で使う際の補足説明を追加
v1.0.0  (2015.7.29)
  • 新規リリース