iOS SDK

iOS SDK実装ガイド

• 過去のバージョン履歴については、こちらのリリースノートを御覧ください。
• Unityの実装手順については, こちらをご確認ください。
• ご質問がある方は、support@tenjin.comまでお問い合わせください。

注:

• v1.12.0以上のバージョンのiOS SDKを使用する場合は、Xcode 12の使用が必要となります。
• AppTrackingTransparencyを使用する場合、.plistファイルのアップデート、Privacy - Tracking Usage Description (NSUserTrackingUsageDescription)の追加及びユーザに表示するテキストメッセージの追加を行ってください。当ライブラリはiOS 14.0以上で使用可能となります。
• Appleサーチアドアトリビューションをお使いの場合、SDKのバージョンをv1.12.6以上にし、AdServices.frameworkライブラリを追加してください。当ライブラリはiOS 14.3以上で使用可能となります。

目次

• SDK実装手順
  • ATTrackingManagerを使用した場合のTenjinの初期化処理
    • ATT許可プロンプトの表示
      • ユーザー追跡の説明の設定
  • SKAdNetworkとコンバージョンバリュー
    • SKAdNetworkとiOS 15+広告主向けポストバック
  • GDPR対応
  • デバイスパラメータ
• アプリ内課金イベント
  • サブスクリプション課金
• カスタムイベント
• サーバ間インテグレーション
• アプリサブバージョン
• インプレッションレベル広告収益
• Live Opsキャンペーン
• カスタマーユーザID

SDK実装手順

Cocapods

podsをお使いの場合、Podfileにpod 'TenjinSDK'を追加後、pod install コマンドを実行してください。その後手順5にお進みください。

Swift Package Manager

SPM を使用する場合は、Xcode 経由でこのリポジトリを使用して Tenjin の SDK パッケージを追加し、手順5に進みます。

1. こちらより最新のSDKコンテンツをダウンロードします。

2. libTenjinSDK.a と TenjinSDK.h をプロジェクトにドラッグします。32ビットのiOSシミュレーターデバイス(i386)をお使いの場合、libTenjinSDK.aの代わりにlibTenjinSDKUniversal.aをお使いください。

3. 下記フレームワークをプロジェクトに追加します。

• AdServices.framework
• AdSupport.framework
• AppTrackingTransparency.framework
• iAd.framework
• StoreKit.framework

4. ビルド設定に -ObjC のリンカーフラグを追加します。
   

5. AppDelegateファイル(デフォルトはAppDelegate.m)内に#import "TenjinSDK.h"を追加します。

6. Appsページから SDK_KEY を取得します。注: SDK_KEY はアプリごとに一意です。同じアプリに対して最大3つまでキーを作成できます。

   

7a. didFinishLaunchingWithOptionsメソッド内に下記を追加します。

 [TenjinSDK initialize:@"<SDK_KEY>"];
 [TenjinSDK connect];

下記がAppDelegate.mファイル内での実装例です。

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [TenjinSDK initialize:@"<SDK_KEY>"];
    [TenjinSDK connect];

    //All your other stuff
    ...
}

注：Swift 5をお使いの場合、init()の代わりにgetInstance()をお使いください。Swiftを用いたサンプルのアプリについてはこちら。

注: アプリの初回起動だけでなく、すべてのdidFinishLaunchingWithOptionsにこのコードを実装するようにしてください。推奨事項に従わない場合は、適切なサポートを提供できないか、アカウントが停止される可能性があります。

7b. 他サービスでディファードディープリンクを既に使用している場合の初期化例 (7a.と7b.のどちらか一方のみをご使用ください)
もし、他サービスでディファードディープリンクを使用している場合、それらのディープリンクをTenjin側に連携してアトリビューションのロジックと紐付けることが可能です。

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{

    [TenjinSDK init:@"<SDK_KEY>"];

    //get your deep link from your other 3rd party service
    NSURL *url = [NSURL withString: @"your_deep_link"];

    //if you have a deep link that's generated from a third party service then pass it to tenjin to handle the attribution of deep links holistically
    if(url) {
      [TenjinSDK connectWithDeferredDeeplink:url];
    }
    else{
      [TenjinSDK connect];
    }

    //All your other stuff
    //...
}

8. テスト用デバイスを追加し、TenjinのSDKデバッガツールを用いてイベントが正しく送信されているか確認します。

ATTrackingManagerを使用した場合のTenjinの初期化処理

iOS 14では、ATTrackingManagerを使用して許可プロンプトを表示し、ユーザをオプトイン/オプトアウトする事が可能です。デバイスがトラッキングの許可を行わない場合は、IDFAはゼロとなります。デバイスがトラッキングの許可を行った場合、connect()メソッドを通じてIDFAがサーバ側に送られます。

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{

    [TenjinSDK init:@"<SDK_KEY>"];

    if (@available(iOS 14, *)) {
        [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
            [TenjinSDK connect];
        }];
    } else {
        [TenjinSDK connect];
    }
}

ATT許可プロンプトの表示

AppleのATTガイドラインに準拠するには、ATT許可プロンプトの説明を入力し、アプリケーションへの許可リクエストを実装する必要があります。

Note: ゲーム内で広告を配信する前に、許可リクエストを実装する必要があります。

ユーザー追跡の説明の設定

XcodeプロジェクトのInfo.plistファイル内のNSUserTrackingUsageDescriptionキーを使用して説明の内容を設定します。デバイス追跡データの使用許可を要求している理由をユーザーに通知するメッセージを提供する必要があります。

• Xcodeプロジェクトナビゲータで、 Info.plistファイルを開きます。
• プロパティリストエディタの任意のキーの横にある追加ボタン（+）をクリックして、新しいプロパティキーを作成します。
• キー名 NSUserTrackingUsageDescriptionを入力します。
• 文字列値のタイプを選択します。
• 値フィールドにアプリ追跡のメッセージを入力します。いくつかの例が含まれます：
  • お客様のデータを使用して、より優れたパーソナライズされた広告エクスペリエンスを提供します。
  • 使用しているアプリ、使用しているデバイス、使用している国に基づいて、最も興味のあるアプリや製品の広告を表示するようにしています。
  • 私たちは、あなたが使用するアプリに基づいて、あなたにとって最も興味深いアプリや製品の広告を表示しようとします。

注: Appleは、プライバシー関連の機能に直面しているすべてのエンドユーザーの許容可能な使用とメッセージングを定義する特定のアプリストアガイドラインを提供しています。Tenjinは法律上の助言を提供していません。したがって、このページの情報は、お客様のビジネスとプロセスの法的要件、およびそれらに対処する方法を決定するための法的手段の代替ではありません。

SKAdNetworkとコンバージョンバリュー

SKAdNetworkの導入に従って, TenjinではupdatePostbackConversionValue(_:)のラッパーメソッドを用意しています。このメソッドは、該当のSKAdNetworkのメソッドをコールし、コンバージョンバリューをTenjinのサーバに送信します。

updatePostbackConversionValue(_:)の6ビットの値はアプリ内イベントに対応する値で、バイナリ値ではなく0-63の間の整数値である必要があります。これ以外の数値の場合、サーバ側でエラーとなります。

SKAdNetwork 4.0がサポート対象となるiOS 16.1以降で、coarseValue(文字列、可能な引数はlow、medium, high)とlockWindow(真偽値)を更新ポストバックメソッドのパラメーターとして送信できるようになりました。

updatePostbackConversionValue(_ conversionValue: Integer, coarseValue: String)

updatePostbackConversionValue(_ conversionValue: Integer, coarseValue: String, lockWindow: Bool)

• SKAdNetwork 4.0に対応したiOSバージョン16.1以降では、このメソッドを何度でも呼び出すことができ、コンバージョンバリューを以前の値よりも低くしたり高くしたりできます。

• 4.0より前のSKAdnetWorkバージョンをサポートする16.1より前のiOSバージョンの場合、このメソッドを呼び出すと、SDKが自動的にiOSバージョンを検出し、conversionValueのみを更新します。

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{

    [TenjinSDK initialize:@"<SDK_KEY>"];
    [TenjinSDK connect];

    //
    // This will call [SKAdNetwork updatePostbackConversionValue: <YOUR 6 bit value>]
    // and also send conversion value to our servers.
    //
    // You will need to use a value between 0-63 for <YOUR 6 bit value>.
    //
    [TenjinSDK updatePostbackConversionValue: <YOUR 6 bit value>];
    
    // For iOS 16.1+ (SKAN 4.0)

    [TenjinSDK updatePostbackConversionValue: <YOUR 6 bit value> coarseValue:@"medium"];

    [TenjinSDK updatePostbackConversionValue: <YOUR 6 bit value> coarseValue:@"medium" lockWindow:true];
}

SKAdNetworkとiOS 15+広告主向けポストバック

SKAdNetworkのポストバックにおいて、Tenjinを送信先に設定するためには、下記をご設定ください。

1. XCodeのプロジェクトナビゲーターで、Info.plistを選択します。
2. プロパティリストエディタ上で、keyのそばの追加ボタン(+)をクリックし、リターンを押下します。
3. NSAdvertisingAttributionReportEndpointをkeyの名称として入力します。
4. Typeのカラムで、ポップアップメニューからStringを選択します。
5. https://tenjin-skan.comを入力します。

これらのステップは、Appleのインストラクション: https://developer.apple.com/documentation/storekit/skadnetwork/configuring_an_advertised_appを元にしています。

GDPR対応

GDPRへの対応において、Tenjin SDKではデバイス/ユーザのオプトイン, オプトアウトおよび各デバイスパラメータのオプトイン, オプトアウトが可能です。OptOut()メソッドにより、Tenjinにリクエストが送られることはありません。

オプトイン, オプトアウトの具体例:

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{

  [TenjinSDK initialize:@"<SDK_KEY>"];

  if ([self checkOptInValue]) {
      [TenjinSDK optIn];
  }
  else {
      [TenjinSDK optOut];
  }

  [TenjinSDK connect];

  //All your other stuff
  //..
}

-(BOOL) checkOptInValue
{
  // check opt-in value
  // return YES; // if user opted-in
  return NO;
}

特定のデバイスパラメータをオプトイン,オプトアウトするにはOptInParams() または OptOutParams()メソッドを使用します。OptInParams()メソッドにより指定されたパラメータのみを送信します。OptOutParams()メソッドにより、指定されたパラーメータ以外のパラメータを送信します。

注: Tenjin上で正しくユーザをトラッキングするには、developer_device_idが必要となります。

Google Adsでプロモーションを実施する場合は、 platform、os_version、 locale、device_model、およびbuild_idも追加する必要があります。

特定のデバイスパラメータのみを取得するには、OptInParams()を使用します。下記具体例では、ip_address, advertising_id, developer_device_id, limit_ad_tracking, referrer, and iadのみを取得しています。

[TenjinSDK initialize:@"<SDK_KEY>"];

NSArray *optInParams = @[@"ip_address", @"advertising_id", @"developer_device_id", @"limit_ad_tracking", @"iad"];
[TenjinSDK optInParams:optInParams];

[TenjinSDK connect];

特定のデバイスパラメータ以外のパラメータを取得するには、OptOutParams()メソッドを使用します。下記具体例では、locale, timezone, または build_id以外のパラメータを送信ししています。

[TenjinSDK initialize:@"<SDK_KEY>"];

NSArray *optOutParams = @[@"country", @"timezone", @"language"];
[TenjinSDK optOutParams:optOutParams];

[TenjinSDK connect];

デバイスパラメータ

アプリ内課金イベント実装手順

課金イベントの検証後(SKPaymentTransactionStatePurchased)、 Tenjin側に課金トランザクションを連携することが可能です。

//Get the NSData receipt
NSURL *receiptURL = [[NSBundle mainBundle] appStoreReceiptURL];
NSData *receiptData = [NSData dataWithContentsOfURL:receiptURL];

//Pass the transaction and the receiptData to Tenjin
[TenjinSDK transaction: transaction andReceipt: receiptData];

免責事項: Tenjinで初めて課金イベントを実装する場合は、課金データを使用してユーザー獲得キャンペーンを拡大する前に、使用している他のツールでデータが正しいことを確認してください。

サブスクリプション課金

サブスクリプションイベントの場合、 管理画面よりIAP shared secretを該当のアプリに追加してください。**

注意点：各サブスクリプション期間中に1度だけサブスクリプショントランザクションを送ってください。(例えば、月ごとのサブスクリプションの場合、1月に1度のトランザクション)

以下のタイムラインの例では、トランザクションイベントは「FirstCharge」イベントと「Renewal」イベントでのみ送信する必要があります。トライアル期間中は、Tenjinに取引イベントを送信しないでください。

For more information on subscriptions, please see: Apple documentation on Working with Subscriptions

カスタムイベントの実装手順

注意点: SDK初期化処理の前にカスタムイベントを送らないようにしてください。 初期化処理は各カスタムイベント発生の前に実施する必要があります。

重要：カスタムイベント名は80文字未満に制限してください。 ユニークなカスタムイベント名は500を超えないようにしてください。

カスタムイベントの送信には下記メソッドを使います。:

• sendEventWithName: (NSString *)eventName and

カスタムイベントを利用して、特定のイベントを獲得したユーザの流入元のコスト情報などに紐付けることが可能です。下記が実装例となります。

//send a particular event for when someone swipes on a part of your app
[TenjinSDK sendEventWithName:@"swipe_right"];

また、カスタムイベントにはNSString eventValueを含めることが可能です。 Tenjinは同じeventNameのイベントのカウントまたは総和を計算するのにeventValueを使用します。eventValueはINTEGER形である必要があります。 eventValueがINTEGER型でない場合, イベントは送信されません。

サーバ間インテグレーション

Tenjinはサーバ間のインテグレーションもサポートしております(有償のプロダクト)。ドキュメントをご覧になりたい方は、support@tenjin.comまでメールをお送りいただき、料金についてご相談ください。

アプリサブバージョン

A/Bテストを実施する場合、appendAppSubversionメソッドを用いて、アプリバージョンに固定の数値を付加することが可能です。例えば、アプリのバージョンが1.0.1でappendAppSubversion: @8888をセットすると、レポートされるアプリバージョンは1.0.1.8888となります。データボルトを用いれば、このアプリバージョンごとのパフォーマンスを分析することが可能です。

[TenjinSDK initialize:@"<SDK_KEY>"];
[TenjinSDK appendAppSubversion:@8888];
[TenjinSDK connect];

インプレッションレベル広告収益の実装

Tenjinでは下記のメディエーションプロバイダにおいて、インプレッションレベルの広告収益(ILRD)をサポートしています。

• AppLovin
• Unity LevelPlay
• HyperBid
• AdMob
• Topon

この機能を使用すると、ユーザーへの広告のインプレッションごとに広告収益に対応するイベントを受け取ることができます。この機能を有効にするには、以下の手順に従ってください。

Live Opsキャンペーン

アプリ開発者は、自社サーバーまたはTenjinと連携していないネットワークにカスタムでコールバックを送信できます。これにより、開発者はこれらのユーザーレベルの属性データをリアルタイムで収集して分析できます。以下は、Tenjinのカスタムコールバックを使用した使用例です。

• 内製のデータ分析ツールがある場合、カスタム コールバックを使用すると、デバイス レベルごとに属性データをゲーム内データに関連付けることができます。

• ユーザーのアトリビューションソースに応じて、さまざまなアプリコンテンツを表示します。たとえば、ユーザーAがオーガニックに関連付けられ、ユーザーBが Facebookに関連付けられているとします。ユーザー Bの方がアプリに関心を持っている可能性が高いため、ユーザーがアプリをインストールした後に特別なゲーム内オファーを表示することができます。

より具体的な使用例について相談をご希望の場合は、Tenjinのサクセスマネージャーまでお問い合わせください。

カスタマーユーザID

イベントのパラメーターとして送信するカスタマーユーザー IDを設定および取得できます。

setCustomerUserId(userId: "user_id")
getCustomerUserId()

[TenjinSDK initialize:@"<SDK_KEY>"];
[TenjinSDK setCustomerUserId:@"user_id"];
userId = [TenjinSDK getCustomerUserId];