Manual | AIBeaconSDK for iOS

Language

Swift | Objective-CSwift | Objective-C

Indexes

利用要件Requirements
依存ライブラリDependencies
- AdSupport.framework
- AppTrackingTransparency.framework (iOS 14 以降iOS 14 or above)
導入手順How to install
その他Miscellaneous

利用要件Requirements

▲ Indexes

Xcode 15.4 以降推奨or above (Recommended)
Deployment Target ... iOS SDK 12.0 - 17.5
Bitcode 対応supported
必要な機能Required functions
- プライバシーPrivacy
  - 位置情報サービス ... オンLocation Services ... On
    - 位置情報の利用を許可 ... 常に許可 または このAppの使用中のみ許可ALLOW LOCATION ACCESS ... Always or While Using the App
      - iOS 13 以降 ... または 1度だけ許可iOS 13 or above ... or Allow Once
  - Bluetooth ... 許可 (iOS 13 以降) Always (iOS 13 or above)
- Bluetooth ... オンOn

依存ライブラリDependencies

▲ Indexes

AdSupport.framework

AIBeaconSDK では、 IDFA の収集を行います。
下記のように、プロジェクトに AdSupport.framework を追加する必要があります。

AIBeaconSDK does collect IDFAs.
You need to add AdSupport.framework in your project as follows:

Project Navigator からプロジェクトルートを選択します。
右ペインのサイドメニュー TARGETS から対象のターゲットを選択します。
General セクションへ移動します。
Linked Frameworks and Libraries の + ボタンから AdSupport.framework を選択して追加します。

Select the project root in Project Navigator.
Choose the target in TARGETS in the right pane.
Move to the General section.
Click the + button in Linked Frameworks and Libraries and select and add AdSupport.framework.

※ IDFA を利用するため、アプリ申請時に IDFA の利用目的について回答する必要があります。

「このAppでは下記の目的で広告ID（IDFA）を使用します（該当するすべてを選択）：」では、次の項目を選択して下さい。

「このAppのインストールを、以前に提供した広告と関連付ける」
「このApp内で行われたアクションを、以前に提供した広告と関連付ける」

* You need to tell the objective of using IDFAs to Apple Inc. when you submit your app.

In "This app uses Advertising identifier to (select all that apply):", select the following items.

"Attribute this app installation to a previously served advertisement"
"Attribute an action taken within this app to a previously served advertisement"

AppTrackingTransparency.framework

iOS 14 以降で利用する場合は、プロジェクトに AppTrackingTransparency.framework を追加する必要があります。
上記 AdSupport.framework と同様の手順で追加して下さい。

また、 iOS 13 以前でも動作させるため、ターゲットの [Build Phases] -> [Link Binary With Libraries] から AppTrackingTransparency.framework の [Status] を Optional に変更して下さい。

If you want to use it on iOS 14 or above, you need to add AppTrackingTransparency.framework to your project.
Add it in the same way as AdSupport.framework above.

Also, change [Status] of AppTrackingTransparency.framework from [Build Phases] -> [Link Binary With Libraries] of the target to Optional so that it will work on iOS 13 or earlier.

導入手順How to install

▲ Indexes

基本設定Basic setting

AIBeaconSDK.framework を導入Setup AIBeaconSDK.framework

AIBeaconSDK.framework を任意の場所に配置します。
以下、AIBeaconSDK を導入する Xcode プロジェクト内での操作です。

Place AIBeaconSDK.framework in any folder you like.
In the Xcode project you're installing AIBeaconSDK to, you need the following operations:

Project Navigator からプロジェクトルートを選択します。
右ペインのサイドメニュー TARGETS から対象のターゲットを選択します。
General セクションへ移動します。
Linked Frameworks and Libraries の + ボタン -> 'Add Other...' ボタンから、先ほど配置した AIBeaconSDK.framework を選択して追加します。
AIBeaconSDK を利用する各ファイルにインポートします。

Select the project root in Project Navigator.
Choose the target in TARGETS in the right pane.
Move to the General section.
Click the + button and 'Add Other...' button in Linked Frameworks and Libraries and select and add AIBeaconSDK.framework you placed.
Import AIBeaconSDK.framework to each file to use AIBeaconSDK.

MyClass.m

@import AIBeaconSDK;

Swift で利用する場合は、 Bridging-Header ファイルを作成して下記内容を記述します。
(例: ObjC-Bridging-Header.h)

If you use this SDK in Swift, you need to create a Bridging-Header file and add the flollowing content.
(ex: ObjC-Bridging-Header.h)

ObjC-Bridging-Header.h

@import AIBeaconSDK;

作成した Bridging-Header ファイルのパスを、
Build Settings の Swift Compiler - General > Objective-C Bridging Header に設定します。
Bridging-Header の設定が完了したら、各ファイルにインポートして利用します。

Set the path of the created Briding-Header file to
Swift Compiler - General > Objective-C Bridging Header in Build Settings.
After this configuration of Bridging-Header, import and use it.

MyClass.swift

import AIBeaconSDK

Info.plist の設定Set Info.plist

次に、プロジェクトの Info.plist を設定します。

NSLocationAlwaysAndWhenInUseUsageDescription および NSLocationWhenInUseUsageDescription プロパティを追加して下さい。

Info.plist

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>[位置情報の利用を常に許可することを、ユーザに要求するメッセージを設定します。]</string>

Info.plist

<key>NSLocationWhenInUseUsageDescription</key>
<string>[位置情報の利用をアプリ使用中のみ許可することを、ユーザに要求するメッセージを設定します。]</string>

Set the Info.plist of your project.

Add the NSLocationAlwaysAndWhenInUseUsageDescription and NSLocationWhenInUseUsageDescription property.

Info.plist

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>[Set the message to tell the user to allow the usage of the location information at any time.]</string>

Info.plist

<key>NSLocationWhenInUseUsageDescription</key>
<string>[Set the message to tell the user to allow the usage of the location information only while she/he is using the app.]</string>

位置情報の利用をアプリ使用中のみに制限したい場合は、 AIBeaconManagerInitOptionKeysRequestLocationServiceAuthorizationType オプションに AIBeaconRequestLocationServiceAuthorizationTypeWhenInUse を設定して下さい。

To restrict the usage of the location information only while using the app, set AIBeaconRequestLocationServiceAuthorizationTypeWhenInUse to AIBeaconManagerInitOptionKeysRequestLocationServiceAuthorizationType.

To restrict the usage of the location information only while using the app, set AIBeaconRequestLocationServiceAuthorizationTypeWhenInUse.rawValue to AIBeaconManagerInitOptionKeysRequestLocationServiceAuthorizationType.

※ ただし、位置情報の利用をアプリ使用中のみに制限した場合は、アプリがバックグラウンド状態または起動していない状態で AIBeacon を検知できなくなります。

* Remark that your app cannot detect AIBeacon in background or not running state if the usage of the location information is restricted to only while the user is using the app.

iOS 10 からは、ユーザデータなどへアクセスする際に使用目的を明記する必要があるため、
NSBluetoothPeripheralUsageDescription プロパティを追加して下さい。

Info.plist

<key>NSBluetoothPeripheralUsageDescription</key>
<string>[Bluetooth へのアクセスをユーザに要求するメッセージを設定します。]</string>

For iOS 10 or above, you must write the objective of the usage clearly to access the user data,
so add the NSBluetoothPeripheralUsageDescription property.

Info.plist

<key>NSBluetoothPeripheralUsageDescription</key>
<string>[Set the message to request the user to access Bluetooth.]</string>

AIBeaconSDK 以外で上記プロパティ設定を既に行っている場合は、新たに追加する必要はありません。
AIBeaconSDK の導入で新たに追加される場合は、AIBeacon を利用する目的を <string> 内に設定して下さい。
(例: 「AIBeacon による情報収集に利用します。」)

You don't need to add these properties if you already configured for besides AIBeaconSDK.
Write your objective of using AIBeacon in <string> if you newly add them for installing AIBeaconSDK.
(ex: "To use for collecting data by AIBeacon.")

iOS 13 以降で利用する場合If you use on iOS 13 or above

iOS 13 から、 NSBluetoothAlwaysUsageDescription を必ず含める必要がある為、
プロジェクトの Info.plist に下記のプロパティを追加して下さい。

Info.plist

<key>NSBluetoothAlwaysUsageDescription</key>
<string>[Bluetooth へのアクセスが必要な理由をユーザーに伝えるメッセージ。]</string>

For iOS 13 or above, you should include NSBluetoothAlwaysUsageDescription,
add the following property to Info.plist of your project.

Info.plist

<key>NSBluetoothAlwaysUsageDescription</key>
<string>[A message that tells the user why the app needs access to Bluetooth.]</string>

AIBeaconSDK 以外で上記プロパティ設定を既に行っている場合は、新たに追加する必要はありません。
AIBeaconSDK の導入で新たに追加される場合は、AIBeacon を利用する目的を <string> 内に設定して下さい。
(例: 「AIBeacon による情報収集に利用します。」)

You don't need to add these properties if you already configured for besides AIBeaconSDK.
Write your objective of using AIBeacon in <string> if you newly add them for installing AIBeaconSDK.
(ex: "To use for collecting data by AIBeacon.")

iOS シミュレータで利用する場合If you use on iOS Simulator

通常版の AIBeaconSDK パッケージに含まれる AIBeaconSDK.framework には、iOS シミュレータ用のアーキテクチャの i386 及び x86_64 は含まれません。
そのため、 iOS シミュレータでビルドを行う場合に以下のような Apple Mach-O Linker Error が発生します。

Xcode

Undefined symbols for architecture x86_64:
...
  "_OBJC_CLASS_$_AIBeaconManager", referenced from:
      objc-class-ref in XXXXXX.o
...
ld: symbol(s) not found for architecture x86_64

これを解決するには、 AIBeaconSDK 配布サイトから with Simulators 版のパッケージをダウンロードしてご利用下さい。
(with Simulators 版は、各バージョンセクションの「Download (with Simulators)」リンクから、通常版は「Download」リンクからダウンロードが可能です)

※ ただし、リリースの際には iOS シミュレータ向けのアーキテクチャを含めることができない為、 i386 及び x86_64 アーキテクチャを含まない通常版をご利用頂くか、下記のコマンドで対象のアーキテクチャを削除して下さい。 (iOS シミュレータ向けのアーキテクチャを含むと Apple からのリジェクト対象になります)

i386 & x86_64 アーキテクチャ削除コマンド:

The AIBeaconSDK.framework included in the regular version of the AIBeaconSDK package does not include the iOS simulator architectures i386 and x86_64.
Therefore, the following Apple Mach-O Linker Error occurs when building with iOS simulator.

Xcode

Undefined symbols for architecture x86_64:
...
  "_OBJC_CLASS_$_AIBeaconManager", referenced from:
      objc-class-ref in XXXXXX.o
...
ld: symbol(s) not found for architecture x86_64

To solve this problem, download the package 'with Simulators' version from AIBeaconSDK Distribution Site and use it.
('with Simulators' version can be downloaded from "Download (with Simulators)" link in each version section, regular version can be downloaded from "Download" link)

* However, since it is not possible to include the architecture for iOS simulator at the time of release, please use the regular version which does not include the i386 and x86_64 architectures or delete the target architectures with the following command. (Including the iOS simulator architecture is subject to rejection from Apple)

i386 and x86_64 architectures delete command:

bash

$ cd /path/to/AIBeaconSDK.framework
$ lipo -remove i386 -remove x86_64 -output AIBeaconSDK AIBeaconSDK

SDK 利用設定Settings for AIBeaconSDK

AIBeaconManager の初期化Initializing AIBeaconManager

AIBeaconSDK 利用にあたり、先ずは AIBeaconManager の初期化を行います。
[Your App ID] 、 [Your API Key] のアプリ情報には、弊社から提供する値を設定します。
アプリ情報は AIBeaconSDK 配布サイト > App Info からご確認いただけます。

以下のように application(_:didFinishLaunchingWithOptions:)application:didFinishLaunchingWithOptions: を実装し、 init(appId:apiKey:)initWithAppId:apiKey: または init(appId:apiKey:options:)initWithAppId:apiKey:options: メソッドを呼び出します。

To use the AIBeaconSDK, you need to initialize AIBeaconManager first.
Set the values we provided to app information of [Your App ID], and [Your API Key].
App information can be found at the AIBeaconSDK distribution site > App Info.

Implement application(_:didFinishLaunchingWithOptions:)application:didFinishLaunchingWithOptions: and call init(appId:apiKey:)initWithAppId:apiKey: or init(appId:apiKey:options:)initWithAppId:apiKey:options: method as follows:

AppDelegate.swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool {
    var aiBeaconManager: AIBeaconManager? = AIBeaconManager(appId: "[Youra App ID]", apiKey: "[Your API Key]")

    ...

    return true
}

AppDelegate.m

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    AIBeaconManager * aiBeaconManager = [[AIBeaconManager alloc] initWithAppId:@"[Your App ID]" apiKey:@"[Your API Key]"];

    ...

    return YES;
}

AIBeacon サービスへの登録Registration to AIBeacon Service

AIBeaconManager の初期化が終わったら、次は AIBeacon サービスへの登録処理を行います。
自動サービス登録 ( AIBeaconManagerInitOptionKeysAutoServiceRegistrationEnabled ) を有効にしている場合は、登録処理が自動で行われるので下記の実装は必要ありません。

registerService()registerService を呼び出して AIBeacon サービスへの登録を行います。

After initializing AIBeaconManager, you need to register to AIBeacon service.
If you enable auto registration of the service ( AIBeaconManagerInitOptionKeysAutoServiceRegistrationEnabled ), you don't need the following implementation because the registration is automated.

Call registerService()registerService and register to AIBeacon service.

MyClass.swift

AIBeaconManager.sharedInstance().registerService()

MyClass.m

[[AIBeaconManager sharedInstance] registerService];

AIBeacon のモニタリング開始Start monitoring AIBeacon

startAiBeaconMonitoring()startAiBeaconMonitoring を呼び出して AIBeacon のモニタリングを開始します。

Call startAiBeaconMonitoring()startAiBeaconMonitoring and start monitoring of AIBeacon.

MyClass.swift

AIBeaconManager.sharedInstance().startAiBeaconMonitoring()

MyClass.m

[[AIBeaconManager sharedInstance] startAiBeaconMonitoring];

プッシュ通知設定Settings for push notification

※ AIBeacon のプッシュ通知機能を利用する場合は以下の手順が必要です。

APNs を有効にします。

Certificates, Identifiers & Profiles から対象アプリの App ID の Push Notifications を有効にします。
プッシュ通知証明書を作成し、 CERTIFICATE と RSA PRIVATE KEY を弊社にご連絡下さい。
(弊社で AIBeacon コンソールへの登録作業を行います)

* You need the following procedure to enable the push notification of AIBeacon.

Enable APNs.

Enable Push Notifications of the App ID of the target app in Certificates, Identifiers & Profiles.
Create the certification of the push notification and please send to us the CERTIFICATE and RSA PRIVATE KEY .
(We will register to the AIBeacon Console)

次に、 AIBeacon のプッシュ通知機能を有効にします。
AIBeaconManagerInitOptionKeysPushNotificationEnabled オプション、もしくは setPushNotificationEnabled(_:)setPushNotificationEnabled: メソッドを利用してプッシュ通知機能を有効にします。
オプションで有効にした場合は、 AIBeaconManager 初期化後にプッシュ通知の初期化処理が自動で行われます。
プッシュ通知の初期化処理を任意のタイミングで行いたい場合は、オプションの値に false@(NO) を設定するかオプションを省略して、 setPushNotificationEnabled(_:)setPushNotificationEnabled: メソッドを呼び出して有効にします。

Next, enable the push notification of AIBeacon.
Enable the push notification of AIBeacon by using AIBeaconManagerInitOptionKeysPushNotificationEnabled option of setPushNotificationEnabled(_:)setPushNotificationEnabled: method.
If you use the option, the push notification is initialized automatically after initializing AIbeaconManager.
If you want to initialize the push notification at any time you like, set the value false@(NO) to the option or omit to configure it and call setPushNotificationEnabled(_:)setPushNotificationEnabled: method and enable the push notification.

MyClass.swift

let options: [String : Any] = [AIBeaconManagerInitOptionKeysPushNotificationEnabled : true]
var aiBeaconManager: AIBeaconManager = AIBeaconManager(appId: "[Your App ID]", apiKey: "[Your API Key]", options: options)

// or

AIBeaconManager.sharedInstance().setPushNotificationEnabled(true)

MyClass.m

NSDictionary<NSString *, id> * options = @{AIBeaconManagerInitOptionKeysPushNotificationEnabled: @(YES)};
AIBeaconManager * aiBeaconManager = [[AIBeaconManager alloc] initWithAppId:@"[Your App ID]" apiKey:@"[Your API Key]" options:options];

// or

[[AIBeaconManager sharedInstance] setPushNotificationEnabled:YES];

AppDelegateProxy が無効の場合If AppDelegateProxy is disabled

AppDelegateProxy ( AIBeaconManagerInitOptionKeysAppDelegateProxyEnabled ) を無効にした場合は、下記のプッシュ通知処理を実装する必要があります。

If AppDelegateProxy ( AIBeaconManagerInitOptionKeysAppDelegateProxyEnabled ) is disabled, you need to implement the following push notification process.

AIBeacon サービスへのデバイストークン登録処理を実装します。
※ AppDelegateProxy が有効な場合でも、自動サービス登録 ( AIBeaconManagerInitOptionKeysAutoServiceRegistrationEnabled ) を無効にした場合は次の実装が必要です。

setApnsDeviceToken(_:)setApnsDeviceToken: を呼び出してAIBeacon サービスへのデバイストークン登録を行います。

Implement the registration of the device token to AIBeacon service.
* Even if AppDelegateProxy is enabled, if you disable automatic service registration ( AIBeaconManagerInitOptionKeysAutoServiceRegistrationEnabled ), you need the following implementation.

Call setApnsDeviceToken(_:)setApnsDeviceToken: and registration of the device token to AIBeacon service.

AppDelegate.swift

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    AIBeaconManager.sharedInstance()?.setApnsDeviceToken(deviceToken)
}

AppDelegate.m

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [[AIBeaconManager sharedInstance] setApnsDeviceToken:deviceToken];
}

プッシュ通知からアプリを起動した際の処理を実装します。
AIBeaconManagerInitOptionKeysAppLaunchOptions オプションに launchOptions を設定します。

Implement the procedure when the push notification starts your app.
You need to set launchOptions to AIBeaconManagerInitOptionKeysAppLaunchOptions option.

AppDelegate.swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]? = nil) -> Bool {
    let options: [String: Any] = [AIBeaconManagerInitOptionKeysPushNotificationEnabled: true,
                                  AIBeaconManagerInitOptionKeysAppLaunchOptions: launchOptions as Any]
    var aiBeaconManager: AIBeaconManager = AIBeaconManager(appId: "[Your App ID]", apiKey: "[Your API Key]", options: options)

    ...

    return true
}

AppDelegate.m

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    NSDictionary<NSString *, id> * options = @{AIBeaconManagerInitOptionKeysPushNotificationEnabled: @(YES),
                                               AIBeaconManagerInitOptionKeysAppLaunchOptions: launchOptions ? : [NSNull null]};
    AIBeaconManager * aiBeaconManager = [[AIBeaconManager alloc] initWithAppId:@"[Your App ID]" apiKey:@"[Your API Key]" options:options];

    ...

    return YES;
}

UNUserNotificationCenterUNUserNotificationCenter のデリゲートを設定します。

Set the delegate of UNUserNotificationCenterUNUserNotificationCenter.

MyClass.swift

import UserNotifications

...

class MyClass: NSObject, UNUserNotificationCenterDelegate {

    ...

    UNUserNotificationCenter.current().delegate = self

MyClass.h

@import UserNotifications;

...

@interface MyClass : NSObject <UNUserNotificationCenterDelegate>

MyClass.m

@implementation MyClass

...

[UNUserNotificationCenter currentNotificationCenter].delegate = self;

通知の受信処理を実装します。
userNotificationCenter(_:willPresent:withCompletionHandler:)userNotificationCenter:willPresentNotification:withCompletionHandler: と userNotificationCenter(_:didReceive:withCompletionHandler:)userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler: を実装し、それぞれで receiveNotification(_:)receiveNotificationWithUserInfo: メソッドを呼び出します。

Implement processing to receive notifications.
Implement userNotificationCenter(_:willPresent:withCompletionHandler:)userNotificationCenter:willPresentNotification:withCompletionHandler: and userNotificationCenter(_:didReceive:withCompletionHandler:)userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler: which are called when the notification is received, and call receiveNotification(_:)receiveNotificationWithUserInfo: method at each implementation.

MyClass.swift

func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    AIBeaconManager.sharedInstance()?.receiveNotification(userInfo: notification.request.content.userInfo)
    completionHandler([])
}

func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
    AIBeaconManager.sharedInstance()?.receiveNotification(userInfo: response.notification.request.content.userInfo)
    completionHandler()
}

MyClass.m

- (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
    [[AIBeaconManager sharedInstance] receiveNotificationWithUserInfo:notification.request.content.userInfo];
    completionHandler(UNNotificationPresentationOptionNone);
}

- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler {
    [[AIBeaconManager sharedInstance] receiveNotificationWithUserInfo:response.notification.request.content.userInfo];
    completionHandler();
}

Entitlements の設定Set Entitlements

Entitlements をプロジェクトに追加します。

プロジェクト設定の {ターゲット} -> [Signing & Capablities] -> [+ Capablity] -> [Push Notifications] を追加する。
下記の内容の Entitlements ファイル (例: {プロジェクト名}.entitlements) をプロジェクトに追加する。

Add Entitlements to your project.

Set On to {Target} -> [Signing & Capablities] -> [+ Capablity] -> [Push Notifications] in the project settings.
Add the Environments file (e.g. {Project Name}.environments) whose content is the following to the project.

MyProject.entitlements

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>aps-environment</key>
    <string>production</string>
</dict>
</plist>

その他Miscellaneous

▲ Indexes

API の詳細については API リファレンスを参照下さい。

Refer the API reference for the details of the API.