6 実装方法

FANSHIP SDKは、Android Studio向けのSDKとなります。
OSおよび各種ライブラリのサポート環境 をご確認の上、下記手順を参考に組み込みを行なってください。

Warning

・Google の位置情報に関するポリシー変更への対応については「6.4 バックグラウンドでの位置情報へのアクセスについて」をご確認ください

・ver4.x.x以降、FCMトークン はアプリモジュール側で取得して FANSHIP SDKへ設定する形式となります。

6.1 Firebase Cloud Messagingの追加

「Android プロジェクトに Firebase を追加する」の手順を参考にアプリプロジェクトにFirebaseを追加します。
Firebaseアシスタントを使用した追加を推奨しております。
Firebaseアシスタントで使用する機能は 「Cloud Messaging」 を選択し、「2 Add FCM to your app」 までを完了させてください。

次に、アプリモジュールbuild.gradleを確認し、編集します。
※ firebase-messagingバージョンは 「2.サポート環境」 をご確認ください。下記バージョンは一例となっております。
　また、アプリプロジェクトの状態やビルド環境によっては、ビルド時に firebase-core が見つからない旨の警告が出る場合がございますので、firebase-messaging バージョンに対応した firebase-core を導入してください。

dependencies {
    implementation 'com.google.firebase:firebase-messaging:17.6.0'
}

Warning

Firebaseの追加に伴い、Firebaseは様々なライブラリの依存関係を持っているため アプリ起動時に 64K参照制限 が発生してクラッシュする可能性があります。
下記参照ページの設定方法を参考にMultidexを有効にすることを強く推奨しております。
参照：64K を超えるメソッドを使用するアプリの設定

6.2 FANSHIP SDKの追加

1. File -> New -> Import Module を選択し、popinfo-sdkを指定して追加してください。
   ※ import時のモジュール名の変更は可能です。バージョン等を追加したモジュール名に変更することを推奨しております。(ver 4.0.0の場合 popinfo-sdk-4.0.0など)
2. settings.gradleにモジュールが追加されていることを確認してください。
3. サポートライブラリ com.android.support:support-v4:28.0.0 または androidx.legacy:legacy-support-v4:1.0.0 が必須となっておりますので、dependenciesに追加してください。
4. アプリモジュールbuild.gradleのdependenciesに上記で追加したライブラリモジュールを追加してください。 ※ File -> ProjectStructure からも追加できます。

dependencies {
    implementation project(':popinfo-sdk-x.x.x')
    implementation 'com.android.support:support-v4:28.0.0'
}

※ 新バージョンのSDKにアップデートする場合のみ、Android Studioにcacheが残っている場合があります。 File -> Invalidate Caches/Restartを行なってください。
※ Android Studioのバージョンによっては、settings.gradleに追加したモジュールが自動で挿入されない場合がございますので、されていない場合は記述を行ってください。

Warning

・サポートライブラリ AndroidX を使用する際は AndroidX を使用するを参考に組み込んでください。
また、組み込み時は gradle.properties の android.enableJetifier を true に設定してください。

[gradle.properties]

android.useAndroidX=true
android.enableJetifier=true

・com.android.tools.build:gradle 3.2.x系か 3.3.x系以上かで FANSHIP SDKライブラリモジュール側の build.gradle に書き換えが必要となります。
ご使用をしているバージョンに合わせどちらかを選択してください。

[popinfo-sdk/build.gradle]

libraryVariants.all {
    // ※ com.android.tools.build:gradle:3.2.x 向け
    //it.generateBuildConfig.enabled = false

    // ※ com.android.tools.build:gradle:3.3.x 〜 向け
    it.generateBuildConfigProvider.configure {
        it.enabled = false
    }
}

6.3 AndroidManifest.xmlの修正

1. permission の追加

下記をコピーしてAndroidManifest.xmlに追加してください。

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

<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

<!-- meta-dataで POPINFO_LOCATION_SOURCESに GPS または Wi-Fi または iBeacon を設定する場合に記述してください -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!-- meta-dataで POPINFO_LOCATION_SOURCESに GPS または Wi-Fi を設定する場合に記述してください -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />

<!-- meta-dataで POPINFO_LOCATION_SOURCESに iBeacon を設定する場合に記述してください -->
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>

<!-- GPS または Wi-Fi または iBeacon をバックグラウンドでも利用する場合に記述してください。
     ※バックグラウンドでも利用する場合、GooglePlay への申請時に別途バックグラウンド位置情報のための申請が必要となります -->
<!-- <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" /> -->

<!-- 「ヘッドアップ通知を維持する」の設定を使用する場合に記述してください -->
<!--<uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" />-->

2. Application Nodes および meta-data の追加

applicationタグ配下 に FANSHIP で使用するクラス および FANSHIP 設定に関する meta-data を追加します。
下記をコピーしてご使用ください。
※ meta-dataの種類につきましては、下記の＜meta-data 一覧＞ を参考に設定の追加／変更をしてください。

<!-- FANSHIP 設定 -->
<provider
    android:name="jp.iridge.popinfo.sdk.PopinfoMessageProvider"
    android:exported="false"
    android:authorities="${applicationId}.popinfo" />

<!-- ウィジェット機能を使用する場合は追加してください。 -->
<receiver android:name="jp.iridge.popinfo.sdk.PopinfoWidget">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>

    <meta-data
        android:name="android.appwidget.provider"
        android:resource="@xml/popinfo_widget" />
</receiver>

<!-- FANSHIP meta-data設定 -->
<meta-data
    android:name="POPINFO_APP_ID"
    android:value="＜FANSHIPのアプリケーションIDを設定してください＞" />

<meta-data
    android:name="POPINFO_MAIN_ACTIVITY_CLASS"
    android:value="auto" />

<meta-data
    android:name="POPINFO_SHOW_SEGMENT_SETTINGS"
    android:value="false" />

<meta-data
    android:name="POPINFO_DEBUG"
    android:value="false" />

<!-- 使用する位置情報の取得方法を設定してください。※ PUSH配信のみ使用する場合 「""」 空の文字列を設定してください。-->
<meta-data
    android:name="POPINFO_LOCATION_SOURCES"
    android:value="GPS,Wi-Fi,iBeacon" />

<!-- Wi-Fi、Bluetooth による来店検知機能を利用する場合 true に設定してください。 -->
<meta-data
    android:name="POPINFO_USES_ANALYTICS"
    android:value="false" />

<!-- 配信タイプ「Push通知のみ」の配信を行う場合は true に設定してください。。-->
<meta-data
    android:name="POPINFO_USES_PUSH_ONLY"
    android:value="false" />

Warning

• FANSHIP SDK 3.x.x以前のバージョンで記述していた FANSHIP SDKで使用するために必要な画面やサービスなどのクラスは、ライブラリモジュールのAndroidManifest.xmlへ記述されています。

• FANSHIP SDKの提供する各画面クラスは縦固定でAndroidManifest.xmlに指定しています。 各 FANSHIP SDKの提供する各画面のorientationやその他属性を変更する場合は、こちらを参考に tools:replace等で設定してください。

3. meta-data 一覧

POPINFO_APP_ID

• 株式会社アイリッジより発番した FANSHIP のアプリ ID を設定します。（必須）

POPINFO_MAIN_ACTIVITY_CLASS

• お知らせ一覧画面からの戻り先 Activity のクラス名を設定します。auto に設定すると、直前に開いていたアプリの画面に戻ります。直前にアプリを開いていなかった場合は、ランチャーから起動する Activity を起動します。

POPINFO_CALLBACK_CLASS

• SDK からコールバックを受け取るクラスのクラス名をパッケージ名を含めて設定します。コールバックを受け取るクラスのサンプルは SDK に同梱の PopinfoCallback.java をご覧ください。（省略時はコールバックを受け取りません）

POPINFO_LOCATION_SOURCES

• 利用する位置情報の取得方法をカンマ区切りで指定します。
  GPS
  　位置連動型送信を使用する場合に指定します。
  Wi-Fi
  　Wi-Fi 連動型送信を使用する場合に指定します。
  iBeacon
  　iBeacon 配信を使用する場合に指定します。
  　指定した種類に応じて一部の permissionの設定は不要になります。
• 位置情報を利用しない場合、空の文字列を指定してください。
• 位置情報に関するダイアログ、設定項目等は自動的に非表示になります。（省略時は GPS のみ有効）

POPINFO_USES_PUSH_ONLY

• 配信タイプ「Push通知のみ」を使用するかどうかを設定します。
  false または 省略 されている状態では、「Push通知のみ」配信を行っても通知は表示されないため、ご使用になる場合はtrueに設定してください。（省略時 false）
  ※ 「Push通知&一覧表示」「一覧表示のみ」配信は設定値に関わらず動作します。

POPINFO_SKIP_INIT_AGREEMENT

• FANSHIP 初回起動時に表示されるインフォメーションダイアログ（位置情報を使用している場合のみ）の表示／非表示を設定します。（省略時 true）
• 表示= false ／ 非表示= 省略 または true

POPINFO_SKIP_PUSH_AGREEMENT

• FANSHIP 初回起動時に表示されるPUSH通知許諾ダイアログの表示／非表示を設定します。非表示にした場合、許諾済みとして動作します。（省略時 false）
• 表示= false ／ 非表示= 省略 または true

POPINFO_USES_ANALYTICS

• サーバーに送信された位置情報を統計的な分析に使用するかどうかを設定します。 Wi-Fi、Bluetooth による来店検知機能を利用する場合は true を設定します。（省略時 false）

POPINFO_SHOW_SEGMENT_SETTINGS

• ユーザー属性設定画面を自動的に表示するかどうかを設定します。trueに設定すると、 FANSHIP のユーザー登録完了時および FANSHIP の設定画面にユーザー属性設定画面への遷移を表示します。（省略時 false）

POPINFO_SHOW_ON_LOCKSCREEN

• 端末がロック状態の時にお知らせポップアップを表示するかどうかを設定します。 ※ 機種・OS固有の問題により正常に動作しない場合もあります。
• true に設定すると、端末がロック状態時にお知らせを受信した時、ポップアップをロック画面上に表示させます。※お知らせ内容を確認する場合ロック画面を解除する必要があります。
• また設定画面にロック画面上にポップアップ通知を行うかどうかの項目を FANSHIP 設定画面に表示します。（省略時 false）

POPINFO_USES_POPUP_ANDROID_Q_OR_HIGHER

• Android 10以上の端末でポップアップを表示するかどうかを設定します。
• true に設定すると、アプリがフォアグラウンドの際にポップアップを表示します。（省略時 false）
• OS の仕様により、Android 10以上の端末ではバックグラウンド時のポップアップ表示はできませんのでご注意ください。

POPINFO_DEBUG

• 各種デバッグ情報を LogCat に出力するかどうかを設定します。※popinfo ID の取得～PUSH 通知受信準備完了（通知受信可能状態）までの処理の結果が画面上に Toastで表示されます。
• popinfo ID や FCMトークン が正常に取得できているかどうか確認する際にご使用ください。※リリース時は必ず false に変更してください。（省略時 false）

POPINFO_EVENTACTION_DEBUG

• イベントトラッキングのデバッグ情報を出力するか設定します。イベントトラッキングが付与された際にキー名を Toast で画面上に表示します。
• 「アプリ内メッセージ」を利用する際、「カスタムイベント」が正常なタイミングで付与されているかなどを確認する際にご使用ください。※リリース時は必ず false に変更してください。（省略時 false）
• バックグラウンド状態やアプリ内メッセージが表示されている状態だと Toast は表示されません

POPINFO_SKIP_INIT_BACKGROUND_LOCATION

• FANSHIP 初回起動時に表示されるバックグラウンド位置情報許諾ダイアログの表示／非表示を設定します。（省略時 false）
• この設定は Android 11 以上の端末で、アプリが targetSdkVersion 30 以上にしている場合にのみ使用されます

Warning

• POPINFO_POPUP_ONLYとPOPINFO_POPUP_IS_OPTIONAL 設定につきましては、v3.5.x 以降では、各種レイアウト／画面クラス内で設定・制御することができるようになったため、廃止しました。必要に応じてソースコード内で実装してください。
• POPINFO_SKIP_INIT_AGREEMENT 省略時の動作が変更されました。
  FANSHIP ver3.5.4以降は、通常組み込み時のインフォメーションダイアログは非表示となります。
  ※従来どおり表示するには、POPINFO_SKIP_INIT_AGREEMENT を false で設定してください。

6.4 バックグラウンドでの位置情報へのアクセスについて

バックグラウンドで位置情報へアクセスするアプリは、データのアクセス等についてアプリ内でユーザーに開示をする必要があります。
「2. Application Nodes および meta-data の追加」にあります POPINFO_SKIP_INIT_AGREEMENT を false に設定して、インフォメーションダイアログを表示してください。

<meta-data
    android:name="POPINFO_SKIP_INIT_AGREEMENT"
    android:value="false" />

※位置情報を利用しない組み込み（GPS、Wi-Fi、iBeacon のいずれも使用しない）をしております場合は不要です
※位置情報をフォアグラウンドのみで利用する場合（android.permission.ACCESS_BACKGROUND_LOCATION を削除している場合）は不要です

Note

Google の位置情報に関するポリシーに変更が入り、バックグラウンドで位置情報へアクセスするアプリは通常の申請とは別に承認を受ける必要ができました。

参照 : バックグラウンドでの位置情報へのアクセスをリクエストする

この項の設定は承認を受けるために必要となる 「アプリ内での開示」 について、インフォメーションダイアログを使用して開示の文言を表示する方法となります。

※アプリ内での開示に関する要件は 2020年 11月現在のものをベースにしております
※文言の内容は res/values/popinfo_strings.xml よりカスタマイズが可能です

6.5 FANSHIP の開始

FANSHIP を開始するためにソースコードへ記述します。

1. FANSHIP の起動

下記のメソッドを、FANSHIP を開始したいタイミングで呼び出してください。
このメソッドは、アプリが起動される度に呼び出される必要があるため、通常はメインActivityのonCreate()メソッド内で呼び出します。

Popinfo.start(this); // this はContext

Warning

• 旧バージョンで FANSHIP 機能の開始メソッドとして使用していたPopinfo.checkStatus(Context context)を廃止しました。
• Popinfo.start()の呼び出しは、メインスレッド上で呼び出してください。

2. FANSHIP へのFCMトークン設定

FCMトークンが取得されたタイミングで下記メソッドを呼び出してください。
通常は、Firebaseライブラリが提供しているトークン生成メソッド内で Popinfo.setToken() を呼び出します。
既に Firebaseライブラリを導入済みの状態ですとトークン生成メソッドがコールされない場合もございますので、Application クラスの onCreate() などでも Popinfo.setToken() を呼び出してください。

※ 設定対象トークンは、設定済みのトークンと差分がない限り FANSHIP SDK側の処理は行なわれないため、何度呼び出しても問題ありません。
※ Popinfo.start(Context context)を実装する前でもこちらのメソッドを呼び出しても問題ありません。
※ Application クラスからコールすることが難しいケースにおいては、アプリケーションが起動された最初の処理（例えば、最初に起動される Activity の onCreate など）での呼び出しも可能です。

// 設定対象トークンが null、空文字、FANSHIPサーバーへ設定済みのトークンと差分がない場合は処理されません
Popinfo.setToken(this, FCMトークン);

～～実装例　FCMトークン取得 および FANSHIP への設定～～

＜Firebase実装＞

[MyFirebaseMessagingService.java]

/** FirebaseMessagingServiceを継承したCustomFirebaseMessagingServiceクラスを継承しても問題ありません**/
public class MyFirebaseMessagingService extends FirebaseMessagingService {
    @Override
    public void onNewToken(String token) {
        ～省略～

        // FANSHIP トークンを設定
        Popinfo.setToken(this, token);
    }

    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        ～省略～

        // FANSHIP FCMメッセージ設定
        Popinfo.fcmMessageHandler(this, remoteMessage);
    }
}

[AndroidManifest.xml]

<service
    android:name="パッケージ名.MyFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT"/>
    </intent-filter>
</service>

～～実装例　アプリケーションクラスでの FCMトークン取得 および FANSHIP への設定～～
※firebase-messaging のバージョンにより、FCMトークンの取得方法が異なります。バージョンを確認のうえ、下記のどちらかの実装を行ってください。

public class YourApplication extends PopinfoApplication {
    @Override
    public void onCreate() {
        super.onCreate();

        // 現在の登録トークンを取得し、FANSHIP に設定（firebase-messaging 20.3.0 未満の場合）
        FirebaseInstanceId.getInstance().getInstanceId().addOnSuccessListener(new OnSuccessListener<InstanceIdResult>() {
            @Override
            public void onSuccess(InstanceIdResult instanceIdResult) {
                String token = instanceIdResult.getToken();
                Popinfo.setToken(getApplicationContext(), token);
            }
        });

        // 現在の登録トークンを取得し、FANSHIP に設定（firebase-messaging 20.3.0 以降の場合）
        // FirebaseMessaging.getInstance().getToken().addOnCompleteListener(new OnCompleteListener<String>() {
        //     @Override
        //     public void onComplete(@NonNull Task<String> task) {
        //         if (!task.isSuccessful()) {
        //             return;
        //         }
        //         String token = task.getResult();
        //         Popinfo.setToken(getApplicationContext(), token);
        //     }
        // });

        ・・・
    }
}

3. PopinfoApplication の実装

下記の a, b いずれかを実装しAndroidManifest.xmlに設定してください。

[AndroidManifest.xml]

<application android:name="パッケージ名.YourApplication" ...>

a. アプリ側で独自のアプリケーションクラスを使用している場合
PopinfoApplication クラスを継承したクラスを作成します。

public class YourApplication extends PopinfoApplication {
    @Override
    public void onCreate() {
        super.onCreate();

        ・・・
    }
}

b. 別のライブラリで Application クラスを継承していて PopinfoApplication を継承できない場合
下記のようにカスタム Application クラスの onCreate 内で FANSHIPの初期化を行ってください。

public class YourApplication extends OtherApplication {
    @Override
    public void onCreate() {
        super.onCreate();

        // FANSHIP 初期化
        Popinfo.init(this);

        ・・・
    }
}

Warning

下記メソッドは廃止されました。 Popinfo.init(Aplication aplication) を代わりにご使用ください。
・Popinfo.registerLifecycleCallbacks(Application application)
・Popinfo.registerPopinfoReceiver(Application application)

4. お知らせ一覧画面の呼び出し

お知らせ一覧画面を表示します。 アプリ内の任意のタイミングで下記コードを呼び出します。

PopinfoUiUtils.showPopinfoList(this); // this はContext

※その他各メソッドの詳細につきましては、同梱のpopinfo_javadocをご確認ください。

5. ステータスバーのPUSH通知アイコン指定

• FANSHIP の通知エリアへ表示するアイコンは、@drawable/popinfo_notification_icon をアプリモジュール内で設定してください。
  ※ 通知エリア内のNotificationをカスタマイズしたい場合は、「8.よくあるカスタマイズ方法」をご確認ください。

Warning

@drawable/popinfo_notification_icon が設定されていない場合のデフォルト動作は、アプリアイコンをステータスバーへ表示するため、端末のOS バージョンや解像度によってはうまく表示されない場合があります。
解像度別にステータスバー用のアイコンリソースを設定することを推奨しております。Googleのステータスバーアイコンデザインガイドを参考にアイコンの作成・設定を行なってください

6. 配信タイプ「Push通知のみ」配信を行う場合の設定

配信タイプ「Push通知のみ」配信を行う場合のみ、追加実装が必要となります。
「8.よくあるカスタマイズ方法 - 配信タイプ「Push通知のみ」配信を使用時の処理を行う方法」を参考に実装してください。

7. Android 8.0以上における通知チャンネル指定

• Android 8.0以上では、通知チャンネル設定が必須となっております。
  FANSHIP の通知チャンネル名につきましては、1度でも作成してしまうと、アプリアップデートでも変更できないため
  res/values/popinfo_values.xml 内の popinfo_notification_channel_name の値を確認の上リリースしてください。
  デフォルトの FANSHIP がPUSH通知を受信した時のチャンネル名はInfoとなっております。
  変更する場合は、アプリモジュールの res/values 配下に popinfo_values.xml をコピーして下記の値を修正してください。

<!-- 通知チャンネル名
     Android 8.0以上では通知チャンネル設定が必須となっています、FANSHIP ではアプリ設定画面に表示されるチャンネル名を'Info'に設定してます。
     チャンネル名の変更が必要な場合、値を変更してください。 (最大40文字)
     ※ OSのNotificationChannelの仕様上一度でも作成するとアプリアップデートでも変更できません。 -->
<string name="popinfo_notification_channel_name">Info</string>

6.6 ProGuard 使用時の設定

FANSHIP SDK を組み込んだアプリへProGuard を使用する場合、以下内容をProGuard 設定ファイルへ記述してください。

# FANSHIP SDK proguard setting
-keep class jp.iridge.popinfo.sdk.** { *; }
-dontwarn jp.iridge.popinfo.sdk.**

また、PopinfoCallbackクラスをご使用の場合、以下も記述してください。

-keep class * extends jp.iridge.popinfo.sdk.callback.PopinfoBaseCallback

Warning

-dontwarn jp.co.erii.bluetus.library.BluReceiveはBLU300の機能廃止に伴い記述する必要がなくなりました。