> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Android SDKのセットアップ
> OneSignalのAndroid SDKを使用して、Androidアプリにプッシュ通知とアプリ内メッセージを追加します。
export const SdkReleasesIframe = ({sdkFilter = undefined, viewMode = undefined, height, ...frameProps}) => {
const baseUrl = 'https://onesignal.github.io/sdk-releases';
const buildUrl = (theme, sdkFilter, viewMode) => {
const url = new URL(baseUrl);
const params = new URLSearchParams();
if (theme) {
params.set('theme', theme);
}
if (sdkFilter) {
params.set('sdk', sdkFilter);
}
if (viewMode) {
params.set('viewMode', viewMode);
}
if (params.toString()) {
url.search = params.toString();
}
return url.toString();
};
const detectTheme = () => {
if (document.documentElement.classList.contains('dark')) {
return 'dark';
}
return 'light';
};
const [theme, setTheme] = useState('light');
const [iframeSrc, setIframeSrc] = useState(() => {
const initialTheme = detectTheme();
return buildUrl(initialTheme, sdkFilter, viewMode);
});
useEffect(() => {
const currentTheme = detectTheme();
setTheme(currentTheme);
setIframeSrc(buildUrl(currentTheme, sdkFilter, viewMode));
const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
const handleThemeChange = () => {
const newTheme = detectTheme();
setTheme(newTheme);
setIframeSrc(buildUrl(newTheme, sdkFilter, viewMode));
};
if (mediaQuery.addEventListener) {
mediaQuery.addEventListener('change', handleThemeChange);
} else {
mediaQuery.addListener(handleThemeChange);
}
window.addEventListener('storage', handleThemeChange);
const observer = new MutationObserver(handleThemeChange);
observer.observe(document.documentElement, {
attributes: true,
attributeFilter: ['class', 'data-theme']
});
return () => {
if (mediaQuery.removeEventListener) {
mediaQuery.removeEventListener('change', handleThemeChange);
} else {
mediaQuery.removeListener(handleThemeChange);
}
window.removeEventListener('storage', handleThemeChange);
observer.disconnect();
};
}, [sdkFilter, viewMode]);
const getIframeHeight = () => {
if (viewMode === 'table') {
return '450';
}
if (viewMode === 'mini') {
return '170';
}
return '800';
};
const iframeHeight = height || getIframeHeight();
return
;
};
このガイドでは、Android Studioを使用してAndroidアプリにOneSignalを追加する方法を説明します。SDKをインストールし、プッシュ通知とアプリ内メッセージを設定し、テストメッセージを送信してすべてが正常に動作していることを確認します。
OneSignalを初めて使用する場合は、手順を順番に進めてください。経験がある場合は、必要なセクションに直接ジャンプしてください。
**AIコーディングアシスタントを使用していますか？**
AI駆動のインストールには、次のプロンプトを使用してください：
```
Integrate the OneSignal Android SDK into this codebase.
Follow the instructions at:
https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/android/ai-prompt.md
```
## ステップ0. OneSignalでFCMを設定する（プッシュ配信に必須）
このステップを完了しなくても、OneSignal Android SDKをインストールして初期化できます。ただし、OneSignalアプリでFirebase Cloud Messaging（FCM）の認証情報が設定されるまで、**プッシュ通知は配信されません**。
会社にすでにOneSignalアカウントがある場合は、アプリを設定するために[管理者ロールとして招待してもらう](./manage-team-members)よう依頼してください。それ以外の場合は、[無料アカウントに登録](https://onesignal.com)して始めましょう。
これらの手順で、OneSignalアプリをFirebase Cloud Messaging（FCM）に接続します。アプリごとに一度だけ行う必要があります。
1. [https://onesignal.com](https://onesignal.com)にログインし、アプリを作成または選択します。
2. **Settings > Push & In-App**に移動します。
3. **Google Android (FCM)**を選択し、セットアップウィザードを**Continue**で進めます。
4. [Firebaseサーバーキーまたはサービスアカウント](./android-firebase-credentials)の詳細を入力します。
5. セットアップウィザードを続行してApp IDを取得します。これはSDKの初期化に使用されます。
完全なセットアップ手順については、[モバイルプッシュセットアップ](./mobile-push-setup)ガイドをご覧ください。
***
## セットアップの契約と要件
このセクションでは、ガイド全体で使用するツール、バージョン、前提条件をまとめています。
* **SDKバージョン：** `5.6.1+`（最新版：[releases](https://github.com/OneSignal/OneSignal-Android-SDK/releases)を確認）
* **AIセットアップ手順：** `https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/android/ai-prompt.md`
* **SDKリポジトリ：** `https://github.com/OneSignal/OneSignal-Android-SDK`
* **Android Studio：** Meerkat+（2024.2.1+）
* **Android API：** 最低23+（Android 6.0+）、推奨31+（Android 12+）
* **デバイス/エミュレータ：** Google Play Servicesがインストールされた Android 7.0+
* **必須依存関係：** `com.onesignal:OneSignal:[5.6.1, 5.9.99]`
* **Applicationクラス：** SDK の適切な初期化に必須
* **App ID形式：** 36文字のUUID（例：`12345678-1234-1234-1234-123456789012`）— OneSignalダッシュボード > Settings > Keys & IDsで確認
* **初期化：** `OneSignal.initWithContext(this, "YOUR_APP_ID")`
* **バッテリー最適化：** バックグラウンド通知に影響する可能性があります
* **推奨：** `OneSignal.login("user_id")`でExternal IDを割り当て、デバイス間でユーザーを統一
***
## Androidセットアップ手順
以下の手順を完了すると：
* AndroidアプリにOneSignal SDKがインストールされ、初期化されます
* 実機でプッシュ通知の権限プロンプトが正しく表示されます
* テストプッシュとアプリ内メッセージが正常に配信されます
\*\*ステップ0（OneSignalでFCMを設定する）\*\*をスキップした場合でも、以下のAndroid Studioのセットアップを完了できます。プッシュ通知のテストや送信の前にステップ0を完了してください。
### ステップ1. OneSignal SDKを追加する
1. Android Studioで、`build.gradle.kts (Module: app)`または`build.gradle (Module: app)`ファイルを開きます
2. `dependencies`セクションにOneSignalを追加します：
```kotlin app/build.gradle.kts theme={null}
implementation("com.onesignal:OneSignal:[5.6.1, 5.9.99]")
```
```groovy app/build.gradle theme={null}
implementation 'com.onesignal:OneSignal:[5.6.1, 5.9.99]'
```
3. **Gradleを同期：** 表示されるバナーの**Sync Now**をクリックするか、**File > Sync Project with Gradle Files**に移動します
Gradleの同期が依存関係の競合なく正常に完了したことを確認してください。
### ステップ2. Applicationクラスを作成して設定する
すべてのエントリポイントで適切なSDKセットアップを確保するため、`Application`クラスの`onCreate`メソッドでOneSignalを初期化することがベストプラクティスです。
**Applicationクラスがまだない場合は作成してください：**
1. **File > New > Kotlin Class/File**（またはJava Class）
2. 名前：`ApplicationClass`（またはお好みの名前）
**Applicationクラスに以下のOneSignalコードを追加してください。**
`YOUR_APP_ID`をDashboard > Settings > [Keys & IDs](./keys-and-ids)で取得した実際のOneSignal App IDに置き換えてください。
```kotlin ApplicationClass.kt theme={null}
// FILE: ApplicationClass.kt
// PURPOSE: Initialize OneSignal when your app launches
// REQUIREMENT: Must be registered in AndroidManifest.xml
package com.your.package.name // Replace with your actual package name
import android.app.Application
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import com.onesignal.OneSignal
import com.onesignal.debug.LogLevel
class ApplicationClass : Application() {
override fun onCreate() {
super.onCreate()
// Enable verbose logging to debug issues (remove in production)
OneSignal.Debug.logLevel = LogLevel.VERBOSE
// Replace with your 36-character App ID from Dashboard > Settings > Keys & IDs
OneSignal.initWithContext(this, "YOUR_APP_ID")
// Prompt user for push notification permission
// In production, consider using an in-app message instead for better opt-in rates
CoroutineScope(Dispatchers.IO).launch {
OneSignal.Notifications.requestPermission(false)
}
}
}
```
```java ApplicationClass.java theme={null}
// FILE: ApplicationClass.java
// PURPOSE: Initialize OneSignal when your app launches
// REQUIREMENT: Must be registered in AndroidManifest.xml
package com.your.package.name; // Replace with your actual package name
import android.app.Application;
import com.onesignal.Continue;
import com.onesignal.OneSignal;
import com.onesignal.debug.LogLevel;
public class ApplicationClass extends Application {
@Override
public void onCreate() {
super.onCreate();
// Enable verbose logging to debug issues (remove in production)
OneSignal.getDebug().setLogLevel(LogLevel.VERBOSE);
// Replace with your 36-character App ID from Dashboard > Settings > Keys & IDs
OneSignal.initWithContext(this, "YOUR_APP_ID");
// Prompt user for push notification permission
// In production, consider using an in-app message instead for better opt-in rates
OneSignal.getNotifications().requestPermission(false, Continue.none());
}
}
```
`Activity`（`MainActivity`など）での初期化は推奨されません。ディープリンクや通知からのコールドスタート時に呼び出されない可能性があるためです。信頼性を確保するため、常に`Application`クラスでOneSignalを初期化してください。
**Applicationクラスを登録する：**
1. アプリの`AndroidManifest.xml`を開きます
2. ``タグに`android:name=".ApplicationClass"`を追加します（異なるクラス名を設定した場合は`.ApplicationClass`を置き換えてください）。
```xml AndroidManifest.xml theme={null}
```
アプリがエラーなくビルドおよび実行されることを確認してください。
### ステップ3. デフォルト通知アイコンを設定する（推奨）
アプリのブランドに合わせて[通知アイコン](./notification-icons)をカスタマイズしてください。このステップはオプションですが、プロフェッショナルな外観のために推奨されます。
### ステップ4. 統合をテストする
**サブスクリプションの作成を確認：**
1. Google Play Servicesが搭載されたデバイスまたはエミュレータでアプリを起動します
2. Dashboard > **Audience > Subscriptions**を確認 — ステータスが「Never Subscribed」と表示されます
3. 権限プロンプトが表示されたら承認します
4. ダッシュボードを更新 — ステータスが「Subscribed」に変わります
[モバイルサブスクリプション](./subscriptions)の作成に成功しました。
モバイルサブスクリプションは、ユーザーがデバイスでアプリを初めて開いたとき、またはアンインストール後に再インストールしたときに作成されます。
#### テストサブスクリプションとセグメントを作成する
1. サブスクリプションの横にある\*\*⋮\*\*をクリック > **Add to Test Users** > 名前を付けます
2. **Audience > Segments > New Segment**に移動します
3. 名前：`Test Users`、**Test Users**フィルターを追加 > **Create Segment**
テストユーザーセグメントの作成に成功しました。
これで、この個別デバイスとテストユーザーグループへのメッセージ送信をテストできます。
#### APIでテストプッシュを送信する
1. \*\*Settings > [Keys & IDs](./keys-and-ids)\*\*に移動します。
2. 提供されたコードで、以下のコードの`YOUR_APP_API_KEY`と`YOUR_APP_ID`を実際のキーに置き換えてください。このコードは先ほど作成した`Test Users`セグメントを使用します。
```bash theme={null}
curl -X POST 'https://api.onesignal.com/notifications' \
-H 'Content-Type: application/json; charset=utf-8' \
-H 'Authorization: Key YOUR_APP_API_KEY' \
-d '{
"app_id": "YOUR_APP_ID",
"target_channel": "push",
"name": "Testing basic setup",
"headings": { "en": "👋" },
"contents": {"en": "Hello world!"},
"included_segments": ["Test Users"],
"big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
}'
```
テストデバイスが以下を含む通知を受信したことを確認してください：
* カスタムアイコン（設定済みの場合）
* 展開時の大きな画像
* Dashboard > **Delivery > Sent Messages**に「Confirmed」ステータスが表示される（無料プランでは利用不可）。
* 通知が届かない？[モバイルプッシュが表示されない](./notifications-show-successful-but-are-not-being-shown)をご覧ください。
* カスタムアイコンがない？アイコン名が`onesignal_small_icon_default`で、正しいdrawableフォルダにあることを確認してください。
* 問題がありますか？APIリクエストとアプリ起動から終了までのログを`.txt`ファイルにコピー＆ペーストし、両方を`support@onesignal.com`に送信してください。
#### アプリ内メッセージをテストする
1. アプリを30秒以上閉じます
2. Dashboard > **Messages > In-App > New In-App** > **Welcome**テンプレートを選択
3. オーディエンス：**Test Users**セグメント
4. トリガー：**On app open**
5. スケジュール：**Every time trigger conditions are satisfied**
6. **Make Message Live**をクリック
7. アプリを開きます
テストデバイスがアプリ内メッセージを受信したことを確認してください。詳細については、[アプリ内メッセージのセットアップ](./in-app-messages-setup)ガイドをご覧ください。
メッセージが表示されない？
* 新しいセッションを開始する
* アプリを30秒以上閉じるかバックグラウンドにしてから再度開く必要があります。これにより新しいセッションが開始されます。
* 詳細については、[アプリ内メッセージの表示方法](./in-app-messages-setup#how-are-iams-displayed%3F)をご覧ください。
* まだ`Test Users`セグメントに含まれていますか？
* 再インストールまたはデバイスを切り替えた場合は、デバイスを[テストサブスクリプション](./test-users)に再追加し、Test Usersセグメントに含まれていることを確認してください。
* 問題がありますか？
* 上記の手順を再現しながら[デバッグログの取得](./capturing-a-debug-log)の手順に従ってください。追加のログが生成され、`support@onesignal.com`に共有していただければ調査をお手伝いします。
OneSignal SDKのセットアップに成功し、次の重要な概念を学びました：
* [サブスクリプション](./subscriptions)の収集、[テストサブスクリプション](./test-users)の設定、[セグメント](./segmentation)の作成。
* セグメントと[メッセージ作成](/reference/create-message) APIを使用した画像付き[プッシュ通知](./push)の送信。
* [アプリ内メッセージ](./in-app-messages-setup)の送信。
このガイドを続けて、アプリ内でユーザーを識別し、追加機能をセットアップしてください。
### 一般的なエラーと修正
| エラー / 症状 | 原因 | 修正方法 |
| ------------------------------------ | -------------------------------- | --------------------------------------------------------- |
| `Cannot resolve symbol 'OneSignal'` | SDK依存関係が追加されていないかGradleが同期されていない | build.gradleに依存関係を追加してプロジェクトを同期する |
| `Application class not found` | Applicationクラスがマニフェストに登録されていない | ``タグに`android:name=".ApplicationClass"`を追加する |
| `Google Play Services not available` | エミュレータ/デバイスにPlay Servicesがない | Play Storeが搭載されたデバイスまたはGoogle APIs搭載のエミュレータを使用する |
| プッシュは受信したがデフォルトのAndroidアイコン | カスタムアイコンが設定されていないか名前が間違っている | `onesignal_small_icon_default`という名前の通知アイコンアセットを作成する |
| プッシュ通知が届かない | FCMがOneSignalで設定されていない | ステップ0を完了：OneSignalダッシュボードでFCM認証情報を設定する |
| アプリ内メッセージが表示されない | セッションが開始されていないかネットワークの問題 | アプリを30秒以上閉じてから再度開き、インターネット接続を確認する |
| `Manifest merger failed` | マニフェスト属性の競合 | 重複するアプリケーション名や権限の競合を確認する |
| バッテリー最適化が通知をブロック | デバイスの電源管理 | ユーザーにアプリのバッテリー最適化を無効にするよう案内する |
| 問題を診断できない | ログ情報が不十分 | 詳細ログを追加し、logcat出力でエラーを確認する |
***
## ユーザー管理
以前、モバイル[サブスクリプション](./subscriptions)の作成方法を説明しました。ここでは、OneSignal SDKを使用して、すべてのサブスクリプション（プッシュ、メール、SMSを含む）を通じて[ユーザー](./users)を識別する方法に拡張します。
### External IDを割り当てる（推奨）
External IDを使用して、バックエンドのユーザー識別子でデバイス、メールアドレス、電話番号を横断してユーザーを一貫して識別します。これにより、チャネルとサードパーティシステム間でメッセージングが統一されます。詳細とJavaコード例については、[モバイルSDKリファレンス](./mobile-sdk-reference)をご覧ください。
```kotlin Kotlin theme={null}
// Call when user logs in or is identified, safe to call multiple times
// Typically used in a login completion handler, or on app launch if already authenticated
fun onUserAuthenticated(userId: String) {
OneSignal.login(userId)
}
// If you want to remove the External ID from the Subscription, setting it to an anonymous user
fun onUserLoggedOut() {
OneSignal.logout()
}
```
OneSignalはサブスクリプション（Subscription ID）とユーザー（OneSignal ID）に対して一意の読み取り専用IDを生成します。
SDKを通じてExternal IDを設定することを強く推奨します。これにより、作成方法に関係なく、すべてのサブスクリプションでユーザーを識別できます。
SDKリファレンスガイドで[`login`メソッド](./mobile-sdk-reference#login-external-id)の詳細をご覧ください。
### タグとカスタムイベントを追加する
タグとカスタムイベントはどちらもユーザーにデータを追加する方法です。タグは`key-value`文字列で、通常はユーザープロパティ（`username`、`role`、`status`など）に関連付けられます。カスタムイベントはJSON形式で、通常はアクション（`new_purchase`、`abandoned_cart`と関連プロパティなど）に関連付けられます。両方とも高度な[メッセージパーソナライゼーション](./message-personalization)とJourneysを駆動するために使用できます。詳細とJavaコード例については、[モバイルSDKリファレンス](./mobile-sdk-reference)をご覧ください。
```kotlin Kotlin theme={null}
// Add a tag when the user's name is set
OneSignal.User.addTag("username", "john_doe")
// Create a custom event when user abandoned a cart
val properties = mapOf(
"product_id" to "123456",
"product_name" to "Product Name",
"product_price" to 100,
"product_quantity" to 1
)
OneSignal.User.trackEvent("abandoned_cart", properties)
```
タグとカスタムイベントの使用方法の詳細については、[タグ](./add-user-data-tags)と[カスタムイベント](./custom-events)ガイドをご覧ください。
### メールおよび/またはSMSサブスクリプションを追加する
プッシュ通知に加えて、メールとSMSチャネルを通じてユーザーにリーチできます。メールアドレスや電話番号がすでにOneSignalアプリに存在する場合、SDKは既存のユーザーに追加します — 重複は作成しません。詳細とJavaコード例については、[モバイルSDKリファレンス](./mobile-sdk-reference)をご覧ください。
```kotlin Kotlin theme={null}
// Add email subscription
// Call when user provides their email (e.g., account creation, settings update) after calling OneSignal.login("user_id")
OneSignal.User.addEmail("user@example.com")
// Add SMS subscription
// Use E.164 format: + country code + number
// Call when user provides their phone number (e.g., account creation, settings update) after calling OneSignal.login("user_id")
OneSignal.User.addSms("+15551234567")
```
マルチチャネルコミュニケーションのベストプラクティス
* メールまたはSMSサブスクリプションを追加する前に明示的な同意を取得してください。
* 各コミュニケーションチャネルの利点をユーザーに説明してください。
* チャネル設定を提供して、ユーザーが希望するチャネルを選択できるようにしてください。
***
### プライバシーとユーザー同意
OneSignalがユーザーデータを収集するタイミングを制御するには、SDKの同意管理メソッドを使用します。詳細とJavaコード例については、[モバイルSDKリファレンス](./mobile-sdk-reference)をご覧ください。
```kotlin Kotlin theme={null}
// In ApplicationClass onCreate(), BEFORE OneSignal.initWithContext()
// Use this if your app requires GDPR or other privacy consent before data collection
OneSignal.consentRequired = true
// Later, after user grants consent (e.g., taps "I Agree" on your consent screen)
OneSignal.consentGiven = true
```
プライバシーとセキュリティドキュメントの詳細：
* [SDKが収集するデータ](./data-collected-by-the-onesignal-sdk)
* [個人データの取り扱い](./handling-personal-data)
***
## プッシュ権限のプロンプト
アプリを開いた直後に`requestPermission()`を呼び出す代わりに、より戦略的なアプローチを取りましょう。アプリ内メッセージを使用して、権限をリクエストする前にプッシュ通知の価値を説明してください。
ベストプラクティスと実装の詳細については、[プッシュ権限のプロンプト](./prompt-for-push-permissions)ガイドをご覧ください。
***
## プッシュ、ユーザー、アプリ内イベントをリッスンする
SDKリスナーを使用して、ユーザーのアクションと状態変化に反応します。`OneSignal.initWithContext()`の後にApplicationクラスに追加してください。
### プッシュ通知イベント
```kotlin Kotlin theme={null}
// Add click listener to handle when users tap notifications
val clickListener = object : INotificationClickListener {
override fun onClick(event: INotificationClickEvent) {
Log.d("OneSignal", "Notification clicked: ${event.notification.title}")
}
}
OneSignal.Notifications.addClickListener(clickListener)
```
### ユーザー状態の変更
以下の例は、プッシュサブスクリプションオブザーバーの使用方法を示しています。ユーザー状態オブザーバーや通知権限オブザーバーなどの他のユーザー状態イベントは、[モバイルSDKリファレンス](./mobile-sdk-reference)で確認できます。
```kotlin Kotlin theme={null}
// Add subscription observer to track push subscription changes
class MyObserver : IPushSubscriptionObserver {
init {
OneSignal.User.pushSubscription.addObserver(this)
}
override fun onPushSubscriptionChange(state: PushSubscriptionChangedState) {
if (state.current.optedIn) {
println("User is now opted-in with push token: ${state.current.token}")
}
}
}
```
### アプリ内メッセージイベント
追加のアプリ内メッセージメソッドは、[モバイルSDKリファレンス](./mobile-sdk-reference)で確認できます。
```kotlin Kotlin theme={null}
// Add click listener for in-app message interactions
val clickListener = object : IInAppMessageClickListener {
override fun onClick(event: IInAppMessageClickEvent) {
print(event.result.actionId)
}
}
OneSignal.InAppMessages.addClickListener(clickListener)
```
***
## 高度なセットアップと機能
### Android固有の機能
* **[通知チャネル](./mobile-sdk-reference#notification-channels)** — 通知をカテゴリに整理する（Android 8.0+）
* **[サービス拡張](./service-extensions)** — 高度な通知カスタマイズ
* **[Huawei/HMSサポート](./huawei-sdk-setup)** — Google Play Servicesの代替
### ユニバーサル機能
* [ディープリンク](./deep-linking) — 通知からユーザーを特定の画面に誘導
* [アクションボタン](./action-buttons) — 通知にインタラクティブなボタンを追加
* [本人確認](./identity-verification) — 安全なユーザー識別
* [位置情報トラッキング](./mobile-sdk-reference#location) — 位置情報ベースのターゲティング
* [インテグレーション](./integrations) — 分析およびデータプラットフォームとの接続
* [多言語メッセージング](./multi-language-messaging) — ローカライズされた通知
SDKメソッドの完全なドキュメントについては、[モバイルSDKリファレンス](./mobile-sdk-reference)をご覧ください。
***
サポートが必要ですか？
サポートチームとチャットするか、`support@onesignal.com`にメールしてください
以下を含めてください：
* 発生している問題の詳細と再現手順（利用可能な場合）
* OneSignal App ID
* 該当する場合は、External IDまたはSubscription ID
* 該当する場合は、OneSignalダッシュボードでテストしたメッセージのURL
* 関連する[ログまたはエラーメッセージ](/docs/ja/capturing-a-debug-log)
お気軽にお問い合わせください！
***