# アプリを構築してテストする DevKit を使用してアプリを構築し、テストする方法をご紹介します。 [GitHub](https://github.com/stripe-samples/terminal-apps-on-devices) の Apps on Devices の導入サンプルリポジトリーにアクセスします。 SmartPOS DevKit デバイスを使用して、デプロイやアプリの審査、署名のプロセスを実行せずに、アプリケーションを繰り返しテストします。 DevKit デバイスが必要な場合は、ダッシュボードの[リーダー](https://dashboard.stripe.com/terminal)セクションから、[ユーザーあたり最大 5 台まで注文](https://docs.stripe.com/terminal/fleet/order-and-return-readers.md)できます。 > #### Verifone リーダーサポート > > Verifone リーダーサポートは、アメリカとカナダでパブリックプレビューです。一部の Verifone リーダーは、アイルランドとイギリス (V660p、UX700、P630)、シンガポール (V660p、P630) 向けにプライベートプレビューです。プレビューに参加するには、営業チームに[連絡して該当するリーダーを注文する必要があります](https://stripe.com/contact/sales)。 ## DevKit を設定する DevKit を使用してアプリを開発する前に、以下を実行する必要があります。 1. 画面の指示に従ってネットワークに接続します。 1. デバイスをお使いの Stripe アカウントに[登録](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=android&reader-type=internet#register-reader)します。 1. 利用可能なすべての更新をインストールします。 初期設定後は、いつでも別のアカウントや店舗に DevKit を登録できます。登録するには、DevKit をインターネットに接続し、手順に従って[リーダーを登録](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=android&reader-type=internet#register-reader)します。 本番環境用デバイスと似ていますが、DevKit デバイスは次の点で異なります。 - [サンドボックス](https://docs.stripe.com/keys.md#test-live-modes)でのみ操作できます。 - [開発者向けオプション](https://developer.android.com/studio/debug/dev-options)と [Android Debug Bridge](https://developer.android.com/studio/command-line/adb) (`adb`) がデフォルトで有効になっている状態で出荷されます。 - デバイスがテスト専用で使用されていることを示すウォーターマークが画面上に表示されます。このウォーターマークは、デバイスの使用中に画面内を移動するため、ユーザーは画面のすべての部分を確認できます。 Terminal API は、登録済みの DevKit デバイスのターゲット設定をサポートします。 ## Stripe デバイス向けのアプリを開発する 以下のステップを使用して、Stripe Android デバイス向けのアプリを開発します。これには、アプリの設定と Stripe リーダーアプリへのハンドオフが含まれます。 ## アプリを設定する [クライアント側] #### Android まず、対面支払いの[導入を設定](https://docs.stripe.com/terminal/payments/setup-integration.md?terminal-sdk-platform=android)します。その後に、以下の Apps on Devices の導入のガイダンスに従います。 ### 依存関係を追加する 次の依存関係をプロジェクトの Gradle ビルドスクリプトに追加します。Apps on Devices の導入には、[Terminal Android SDK](https://github.com/stripe/stripe-terminal-android) バージョン `2.22.0` 以降が必要ですが、Stripe では[最新バージョン](https://github.com/stripe/stripe-terminal-android/releases)の導入をお勧めしています。 #### Kotlin ```kotlin dependencies { implementation("com.stripe:stripeterminal-core:5.3.0") implementation("com.stripe:stripeterminal-appsondevices:5.3.0") } ``` その他の Stripe Terminal SDK の依存関係を使用していないことを確認してください。たとえば、前に Terminal Android SDK を実装したことがある場合は、最上位の `com.stripe:stripeterminal` の依存関係 (例: `com.stripe:stripeterminal:5.3.0`) を使用しないでください。 [アプリのビルドスクリプトに依存関係を含める](https://github.com/stripe-samples/terminal-apps-on-devices/blob/718c2de38c7b8003fcf58c536c266bb990ad43a7/app/build.gradle.kts#L66)の例をご覧ください。 ### アプリケーションを設定する Stripe SDK にライフサイクルイベントを通知するには、[TerminalApplicationDelegate.onCreate()](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal-application-delegate/on-create.html) コールをアプリケーションサブクラスの [onCreate()](https://developer.android.com/reference/android/app/Application#onCreate\(\)) メソッドに追加します。 #### Kotlin ```kotlin class MyApplication : Application() { override fun onCreate() { super.onCreate() TerminalApplicationDelegate.onCreate(this) } } ``` [アプリのマニフェスト](https://developer.android.com/guide/topics/manifest/manifest-intro) で、`android:name` 属性が含まれる `Application` サブクラスの名前を指定します。 > `Application` が Android 15 を実行するデバイスをサポートしていることを確認するには、`targetSdkVersion` を `24` 以降に設定します。 ```xml ``` [導入の設定](https://docs.stripe.com/terminal/payments/setup-integration.md?terminal-sdk-platform=android)の詳細をご覧になるか、[Application サブクラスを正確に設定](https://github.com/stripe-samples/terminal-apps-on-devices/blob/718c2de38c7b8003fcf58c536c266bb990ad43a7/app/src/main/java/com/stripe/aod/sampleapp/MyApp.kt#L10)する例について Apps on Devices サンプルアプリの GitHub リポジトリーをご覧ください。 #### React Native まず、対面支払いの[導入を設定](https://docs.stripe.com/terminal/payments/setup-integration.md?terminal-sdk-platform=react-native)します。その後、以下の Apps on Devices の導入のガイダンスに従います。 ### アプリケーションを設定する Stripe SDK にライフサイクルイベントを通知するには、`TerminalApplicationDelegate.onCreate()` コールを Application サブクラスの [onCreate()](https://developer.android.com/reference/android/app/Application#onCreate\(\)) メソッドに追加します。 #### Kotlin ```kotlin import com.stripeterminalreactnative.TerminalApplicationDelegate class MyApplication : Application() { override fun onCreate() { super.onCreate() TerminalApplicationDelegate.onCreate(this) } } ``` [アプリのマニフェスト](https://developer.android.com/guide/topics/manifest/manifest-intro) で、`android:name` 属性が含まれる `Application` サブクラスの名前を指定します。 ```xml ``` [Application サブクラスの設定](https://github.com/stripe/stripe-terminal-react-native/blob/main/dev-app/android/app/src/main/java/com/dev/app/stripeterminalreactnative/MainApplication.java#L58)の例を確認したい場合は、[導入の設定](https://docs.stripe.com/terminal/payments/setup-integration.md?terminal-sdk-platform=react-native)の詳細をご覧になるか、または React Native GitHub リポジトリのサンプルアプリを参照してください。 ### サーバーレス初期化 Apps on Devices では、バックエンドトークンプロバイダーの代わりに `AppsOnDevicesConnectionTokenProvider` を使用できます。これにより、バックエンドサーバーが接続トークンを提供することなく初期化できます。 ```js import { StripeTerminalProvider, AppsOnDevicesConnectionTokenProvider, } from '@stripe/stripe-terminal-react-native'; function Root() { return ( ); } ``` ## アプリを構築する [クライアント側] Apps on Devices の導入については、以下のガイダンスに従います。 ### リーダーを検出して接続する #### Android > Android SDK のバージョン `5.0.0` では、`easyConnect` メソッドを使用して、リーダーの検出と接続を 1 つの API コールに統合し、統合を簡素化できます。詳細については、[SDK 移行ガイド](https://docs.stripe.com/terminal/references/sdk-migration-guide.md#update-your-reader-connection-usage)を参照してください。 新しい Stripe デバイスを新しい [Reader オブジェクト](https://docs.stripe.com/api/terminal/readers/object.md)としてアカウントに登録する必要があります。デバイスの管理者設定に表示される、[Reader オブジェクトの作成](https://docs.stripe.com/api/terminal/readers/create.md)に必要なペアリングコードを使用します。お使いのアプリは Stripe Terminal Android SDK を使用してデバイスを検出し、接続します。 Apps on Devices の導入サンプルの [GitHub](https://github.com/stripe-samples/terminal-apps-on-devices) リポジトリーで、ハンドオフモードを使用する[検出](https://github.com/stripe-samples/terminal-apps-on-devices/blob/718c2de38c7b8003fcf58c536c266bb990ad43a7/app/src/main/java/com/stripe/aod/sampleapp/model/MainViewModel.kt#L90)方法と[接続](https://github.com/stripe-samples/terminal-apps-on-devices/blob/718c2de38c7b8003fcf58c536c266bb990ad43a7/app/src/main/java/com/stripe/aod/sampleapp/model/MainViewModel.kt#L106)方法の例をご覧ください。 1. 登録済みのデバイスでアプリが実行されます。 1. アプリは、[AppsOnDevicesDiscoveryConfiguration](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-discovery-configuration/-apps-on-devices-discovery-configuration/index.html) を使用して [discoverReaders](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/discover-readers.html) を呼び出すことでリーダーを検出します。 1. [connectReader](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/connect-reader.html) を使用してアプリをリーダーに接続します。 次の例は、Android アプリでハンドオフモードを使用して Stripe リーダーを検出し、接続する方法を示しています。 #### Kotlin ```kotlin private fun discoverReaders() { Terminal.getInstance().discoverReaders(config = AppsOnDevicesDiscoveryConfiguration(), discoveryListener = object : DiscoveryListener { override fun onUpdateDiscoveredReaders(readers: List) { // In Apps on Devices discovery, the list will // contain a single reader. Connect to // the reader after it is discovered. readers.firstOrNull()?.let { reader -> connectReader(reader) } } }, callback = object : Callback { override fun onSuccess() { // Handle successfully discovering readers } override fun onFailure(e: TerminalException) { // Handle exception while discovering readers } } ) } private fun connectReader(reader: Reader) { Terminal.getInstance().connectReader( reader,AppsOnDevicesConnectionConfiguration( object : AppsOnDevicesReaderListener { override fun onDisconnect(reason: DisconnectReason) { // Optionally get notified about reader disconnects (for example, reader was rebooted) } override fun onReportReaderEvent(event: ReaderEvent) { // Optionally get notified about reader events (for example, a card was inserted) } } ), object : ReaderCallback { override fun onSuccess(reader: Reader) { // Handle successfully connecting to the reader } override fun onFailure(e: TerminalException) { // Handle exception when connecting to the reader } } ) } ``` #### React Native > React Native SDK のバージョン `0.0.1-beta.29` では、[easyConnect](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/StripeTerminalSdkType.html#easyconnect) メソッドを使用して、リーダーの検出と接続を 1 つの API コールに統合し、導入を簡素化できます。 新しい Stripe デバイスを新しい [Reader オブジェクト](https://docs.stripe.com/api/terminal/readers/object.md)としてアカウントに登録する必要があります。デバイスの管理者設定に表示される、[Reader オブジェクトの作成](https://docs.stripe.com/api/terminal/readers/create.md)に必要なペアリングコードを使用してください。アプリが Stripe Terminal React Native SDK を使用してデバイスを検出し、接続します。 1. 登録済みのデバイスでアプリが実行されます。 1. アプリは、`appsOnDevices` [検出メソッド](https://stripe.dev/stripe-terminal-react-native/api-reference/modules/Reader.Android.html#DiscoveryMethod)を使用して [discoverReaders](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/StripeTerminalSdkType.html#discoverReaders) を呼び出すことでリーダーを検出します。 1. アプリは、[connectReader](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/StripeTerminalSdkType.html#connectreader-1) 経由でリーダーに接続します。 以下の例は、React Native アプリで Apps on Devices モードを使用して Stripe リーダーを検出し、接続する方法を示しています。 ```js const { discoverReaders, connectReader, discoveredReaders } = useStripeTerminal({ onUpdateDiscoveredReaders: async (readers) => { // After the SDK discovers a reader, your app can connect to it. // The discoverReaders method doesn't resolve until discovery completes, // so use this callback to handle discovered readers. if (readers.length > 0) { const { reader, error } = await connectReader({ discoveryMethod: 'appsOnDevices', reader: readers[0], }); if (error) { console.log('connectReader error:', error); return; } console.log('Reader connected successfully', reader); } }, }); const handleDiscoverReaders = async () => { const { error } = await discoverReaders({ discoveryMethod: 'appsOnDevices', }); if (error) { console.log('discoverReaders error:', error); } }; useEffect(() => { handleDiscoverReaders(); }, [discoverReaders]); ``` ### 支払いを回収する ハンドオフモードを使用してリーダーに接続すると、[支払いの回収](https://docs.stripe.com/terminal/payments/collect-card-payment.md?terminal-sdk-platform=android#create-payment)を開始できます。 Stripe Reader アプリは、支払いの回収やその他の支払い操作 ([支払い情報の保存](https://docs.stripe.com/terminal/features/saving-payment-details/overview.md)など) を処理します。支払い操作を開始すると、Stripe Reader アプリがプライマリになり、全画面で起動します。その後、Stripe Reader アプリがフローを進め、支払いの完了 (成功または失敗) または顧客のキャンセル後に制御をアプリに戻します。制御がアプリに戻ると、Stripe Reader アプリはバックグラウンドで実行され続けます。 [Apps on Devices アプリで支払いを回収](https://github.com/stripe-samples/terminal-apps-on-devices/blob/718c2de38c7b8003fcf58c536c266bb990ad43a7/app/src/main/java/com/stripe/aod/sampleapp/model/CheckoutViewModel.kt#L82)する例をご覧ください。 #### オフラインで支払いを回収する Apps on Devices は、[オフラインでの支払いの回収](https://docs.stripe.com/terminal/features/operate-offline/collect-card-payments.md?terminal-sdk-platform=android&reader-type=internet)をサポートします。 ## デバイス管理 [クライアント側] アプリから `stripe://settings/` ディープリンクの URI を起動することで、デバイスの管理者設定にアクセスできます。 [管理者設定のディープリンク URI の起動](https://github.com/stripe-samples/terminal-apps-on-devices/blob/718c2de38c7b8003fcf58c536c266bb990ad43a7/app/src/main/java/com/stripe/aod/sampleapp/fragment/HomeFragment.kt#L30)の例をご覧ください。 #### Kotlin ```kotlin startActivity( Intent(Intent.ACTION_VIEW) .setData(Uri.parse("stripe://settings/")) ) ``` ## アプリを測定する [クライアント側] Stripe は、アプリケーションレベルの測定ソリューションを提供していません。アプリケーションのクラッシュやその他のログを追跡するには、Sentry や Crashlytics などのサードパーティーのライブラリを使用できます。 ## デバイスのロケールを設定する [クライアント側] デバイスユーザーが選択した言語 (国ではなく) は、[Locale.getDefault()](https://developer.android.com/reference/java/util/Locale#getDefault\(\)) によって返される値に入力されます。デバイスの言語は管理者設定で変更できます。 ## 画面の向き [クライアント側] Stripe Android デバイスでは、_自動回転画面_設定がデフォルトで有効になっています。アプリでは、UI を特定の画面の向きにロックすることで、この設定を上書きできます。 これは、マニフェストで関連する `` タグに [screenOrientation](https://developer.android.com/guide/topics/manifest/activity-element#screen) 属性を設定することで行えます。 ```xml ``` あるいは、`Activity` クラスの [Activity::setRequestedOrientation](https://developer.android.com/reference/android/app/Activity#setRequestedOrientation(int) を使ってプログラムで設定することもできます。 #### Kotlin ```kotlin class MainActivity : Activity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // Lock to portrait orientation requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_PORTRAIT // Or, lock to landscape orientation // requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_LANDSCAPE } } ``` ## 制限 [クライアント側] Stripe Android デバイスでは、戻るボタンやステータスバーなどのシステム UI は表示されません。 アプリが電池残量、充電状態、接続のステータスをユーザーに表示する必要がある場合は、以下の Android API のドキュメントで詳細をご覧ください。 - [電池残量と充電状態を監視する](https://developer.android.com/training/monitoring-device-state/battery-monitoring) - [接続のステータスと種類をモニタリングする](https://developer.android.com/training/monitoring-device-state/connectivity-status-type) ## デバイスアクセサリーを扱う [クライアント側] Stripe リーダーがドックに接続または切断すると、Android オペレーションシステムは[設定の変更](https://developer.android.com/guide/topics/resources/runtime-changes)をトリガーします。 デフォルトでは、設定が変更されるとアプリのアクティビティーは自動的に再作成されます。 ドックの接続時または切断時にアクティビティーの自動再作成を無効にするには、`AndroidManifest.xml` ファイルの `` エントリーに `android:configChanges="uiMode"` を追加します。 ```xml ``` [Activity::onConfigurationChanged](https://developer.android.com/reference/android/app/Activity#onConfigurationChanged\(android.content.res.Configuration\)) を実装することにより、アクティビティーで設定変更が通知されるようにすることができます。このメソッドは、マニフェストで `android:configChanges` 属性で処理する設定を指定している場合にのみ呼び出されます。 ```kotlin class MainActivity : Activity() { override fun onConfigurationChanged(newConfig: Configuration) { super.onConfigurationChanged(newConfig) // implement custom configuration change handling logic } } ``` ## アプリをテストする S700 DevKit デバイスを使用して、Stripe ダッシュボードでアプリをテストするか、Android Debug Bridge (`adb`) を使用してアプリをテストします。 #### Android Debug Bridge (adb) USB-A to USB-C ケーブルを使用して、DevKit デバイスをコンピューターに接続できます。次に、`adb` を使用して、アプリの構築済みの APK を DevKit デバイスに直接インストールします。 以下の例では、アプリケーションの[パッケージ名](https://developer.android.com/studio/build/configure-app-module)が `com.example.myapp` で、[主要なアクティビティー](https://developer.android.com/reference/android/content/Intent.html#ACTION_MAIN)が `MainActivity` であると想定しています。 ``` $ adb install myapp.apk ``` インストールが完了したら、アプリを起動します。 ``` $ adb shell am start com.example.myapp/.MainActivity ``` 管理者設定を開始します。 ``` $ adb shell am start -d "stripe://settings/" ``` 必要に応じて、アプリをアンインストールします。 ``` $ adb uninstall com.example.myapp ``` Google の [Android Debug Bridge のドキュメント](https://developer.android.com/studio/command-line/adb) では、`adb` の使用に関する包括的なガイドが提供されています。 #### ダッシュボード ダッシュボードでアプリをテストするには、以下の手順を実行します。 1. サンドボックスで、[Terminal リーダー](https://dashboard.stripe.com/test/terminal/readers)ページを開きます。 1. まだ登録していない場合は、**リーダーを登録する**をクリックして、お使いのアカウントに DevKit デバイスを[登録](https://docs.stripe.com/terminal/payments/connect-reader.md?reader-type=internet#register-reader)します。 1. **Terminal**\> **Software** をクリックします。 1. [Software](https://dashboard.stripe.com/terminal/software)タブで、デプロイするアプリを選択します。デプロイする新しいアプリを作成することもできます。 1. アプリの詳細ページで、**バージョンをデプロイする**をクリックします。 1. アプリの最新バージョンを選択して、**次へ**をクリックします。 1. DevKit デバイスの[デプロイグループ](https://docs.stripe.com/terminal/features/apps-on-devices/deploy-in-Dashboard.md)を選択し、**次へ**をクリックします。 1. 設定するキオスクアプリを選択して、**次へ**をクリックします。これは、Stripe リーダーがオンになると起動するデフォルトのアプリです。デプロイするアプリが 1 つのみの場合は、代わりにそのアプリを選択します。 1. デプロイの詳細を確認して、**Deploy (デプロイ)** をクリックします。 1. DevKit デバイスを再起動して、アプリをデバイスにデプロイします。 ### トラブルシューティング 以前にサイドロードでアプリをインストールしていた場合、再びデプロイを行おうとすると、`Failed to apply updates. Code: A9-com.example.posapp` (更新の適用に失敗しました。コード: A9-com.example.posapp) というエラーが表示されることがあります。 以下のコマンドを実行して、サイドロードされたアプリを手動でアンインストールする必要があります。 ``` adb uninstall com.example.posapp ``` ## 支払いをテストする DevKit デバイスは、[ダッシュボード](https://dashboard.stripe.com/terminal/shop/thsku_FmpZaTqwezTFvS)で注文できる Stripe のテスト用の物理カードを使用してテスト支払いを処理できます。[支払いをテストする](https://docs.stripe.com/terminal/references/testing.md#physical-test-cards)際に、小数を使用する金額を使用して特定の結果を生成することができます。 > DevKit デバイスで支払いをテストするときに、実際のカードを使用しないでください。 ## 次のステップ - [アプリの審査に向けて準備する](https://docs.stripe.com/terminal/features/apps-on-devices/app-review.md) - [アプリを提出する](https://docs.stripe.com/terminal/features/apps-on-devices/submit.md)