> For the complete documentation index, see [llms.txt](https://developers.fingerpush.com/app-push/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.fingerpush.com/app-push/sdk-manual/android.md).

# Android SDK 매뉴얼

2026년 8월 12일에 업데이트됨

{% hint style="success" %}
Android SDK v3.8.3 (호환성 정보)\
Android API 21+
{% endhint %}

### SDK 설치하기

{% hint style="info" %}
알립니다.

Gradle을 사용할 때, 프로젝트 <mark style="color:blue;">build.gradle</mark> 파일에 <mark style="color:blue;">repositories</mark> 블럭이 있다면 gradle (build.gradle)을, 프로젝트 settings.gradle 파일에 repositories 블럭이 있다면 Gradle (settings.gradle)을 참고해주세요.
{% endhint %}

{% tabs %}
{% tab title="Gradle (build.gradle)" %}
1\. SDK를 설치할 프로젝트 <mark style="color:blue;">`settings.gradle`</mark> 파일의 <mark style="color:blue;">`repositories`</mark> 블럭 안에 mavenCentral() 저장소를 선언하세요.

{% code title="프로젝트 settings.gradle" %}

```
dependencyResolutionManagement {
  ...
  repositories {
    ...
    mavenCentral()
  }
}
```

{% endcode %}

2\. 어플리케이션 build.gradle 파일에서 핑거푸시 SDK 패키지를 추가하세요. 그리고 아래 링크에서 최신버전을 확인하고 $SDK\_VERSION 에 입력하세요.

* SDK 버전 목록: [링크](/app-push/sdk-manual/sdk-down.md)

{% hint style="info" %}
사용 중인 언어에 맞는 코드를 참고해주세요.
{% endhint %}

{% code title="어플리케이션 build.gradle (Groovy)" %}

```groovy
dependencies {
    implementation 'com.fingerpush:sdk-android:SDK_VERSION'
}
```

{% endcode %}

{% code title="어플리케이션 build.gradle.kts (Kotlin DSL)" %}

```kts
dependencies {
    implementation("com.fingerpush:sdk-android:SDK_VERSION")
}
```

{% endcode %}
{% endtab %}

{% tab title="Gradle (settings.gradle)" %}
1\. SDK를 설치할 프로젝트 <mark style="color:blue;">`build.gradle`</mark> 파일의 <mark style="color:blue;">`repositories`</mark> 블럭 안에 mavenCentral() 저장소를 선언하세요.

{% code title="프로젝트 build.gradle" %}

```
allprojects {
    repositories {
        ...
        mavenCentral()
    }
}
```

{% endcode %}

2\. 어플리케이션 build.gradle 파일에서 핑거푸시 SDK 패키지를 추가하세요. 그리고 아래 링크에서 최신버전을 확인하고 $SDK\_VERSION 에 입력하세요.

* SDK 버전 목록: [링크](/app-push/sdk-manual/sdk-down.md)

{% hint style="info" %}
사용 중인 언어에 맞는 코드를 참고해주세요.
{% endhint %}

{% code title="어플리케이션 build.gradle (Groovy)" %}

```groovy
dependencies {
    implementation 'com.fingerpush:sdk-android:SDK_VERSION'
}
```

{% endcode %}

{% code title="어플리케이션 build.gradle.kts (Kotlin DSL)" %}

```kts
dependencies {
    implementation("com.fingerpush:sdk-android:SDK_VERSION")
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

### FCM APP 생성

{% hint style="danger" %}
기존 GCM 프로젝트가 있는 경우, 반드시 기존 GCM 프로젝트를 추가해서 사용해야 합니다.
{% endhint %}

1\) 프로젝트를 추가합니다.

![](https://1606198054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff5XCUiUhwc0T57hW21TH%2Fuploads%2FAJpxvWJK1PYJolgacf1y%2Ffcm_project_add.png?alt=media\&token=b73e69c2-c899-47db-a379-c95902d38ca8)

2\) 앱 추가 후, 다운로드한 'google-services.json' 파일을 프로젝트 앱 모듈 루트 디렉토리로 이동 시킵니다.

![](https://1606198054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff5XCUiUhwc0T57hW21TH%2Fuploads%2Fa8JJG9CknuuUQ1HYEMUE%2Ffcm_app.png?alt=media\&token=dedf9f51-dda4-413d-a122-b555b0ebcb76) ![](https://1606198054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff5XCUiUhwc0T57hW21TH%2Fuploads%2FEPlq7EAeB2IS2oEGbi2T%2Ffcm_download_google_services.png?alt=media\&token=e836c2f6-9eef-4417-978e-4eee402c2032)

3\) '프로젝트 설정 > 서비스 계정' 메뉴로 이동하여 '새 비공개 키 생성' 버튼을 클릭하여 비공개 키(\*.json)를 생성 및 다운로드 받습니다.

<figure><img src="https://1606198054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff5XCUiUhwc0T57hW21TH%2Fuploads%2FF0sHkmuxn3va2DkUlR2I%2Ffcm_create_private_key_1.png?alt=media&amp;token=74685b46-6b02-49d4-a9fc-fce35ac85540" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
비공개 키는 복수로 생성할 수 있으나, 생성된 키는 1회만 다운로드 가능하니 안전한 위치에 저장합니다.
{% endhint %}

<figure><img src="https://1606198054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff5XCUiUhwc0T57hW21TH%2Fuploads%2FwqSQCCJXVHGekgcpRTmy%2Ffcm_create_private_key_2.png?alt=media&amp;token=64da2ebd-4759-4223-9cf2-265c2a77631d" alt="" width="375"><figcaption></figcaption></figure>

4\) 비공개 키를 생성하고 '클라우드 메시징' 메뉴에서 FCM API(V1)이 '사용 중지됨' 된 경우 'Google Cloud Console > APIS' 로 이동하여 사용 설정해야 합니다.

<figure><img src="https://1606198054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff5XCUiUhwc0T57hW21TH%2Fuploads%2Fcc5JmJSK7o94khigjSRK%2Ffcm_api_disabled.png?alt=media&amp;token=66d7aab6-6348-4e5f-ae96-8877c42e54c1" alt=""><figcaption></figcaption></figure>

{% embed url="<https://console.cloud.google.com/apis>" %}

5\) API 항목에서 Firebase Cloud Messaging API 를 선택한 뒤, 사용을 클릭하여 '사용 설정됨' 으로 변경되어 있는지 확인합니다.

<figure><img src="https://1606198054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff5XCUiUhwc0T57hW21TH%2Fuploads%2Fk91kmnwEYQMfWjAvLCoO%2Ffcm_api_enable_2.png?alt=media&amp;token=d6643c19-3eeb-4f02-bcd1-60c6fa33db4e" alt=""><figcaption></figcaption></figure>

### 핑거푸시 사용자 콘솔 APP 생성

1\) 핑거푸시 사용자 콘솔에서 '앱 등록' 버튼을 누른 뒤 앱을 생성합니다.

<figure><img src="https://1606198054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff5XCUiUhwc0T57hW21TH%2Fuploads%2Fj7NMYkJ5YyFTf7OgSAlf%2F%EA%B7%B8%EB%A6%BC43.png?alt=media&amp;token=42b92a00-6a92-4afa-804a-8358cd5a66fd" alt=""><figcaption></figcaption></figure>

2\) '앱 설정' 메뉴로 이동하면 App Key, App Secret을 확인할 수 있습니다.

<figure><img src="https://1606198054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff5XCUiUhwc0T57hW21TH%2Fuploads%2FNF90iIPRAJkS1Ey3Am9z%2F%EA%B7%B8%EB%A6%BC35.png?alt=media&amp;token=88918c90-5671-4219-be20-1915ceeaf982" alt=""><figcaption></figcaption></figure>

3\) 플랫폼 설정 내 FCM > 설정을 클릭하여 다운로드 받은 비공개 키(\*.json) 및 프로젝트 패키지명을 입력하고 등록합니다.

<figure><img src="https://1606198054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff5XCUiUhwc0T57hW21TH%2Fuploads%2FUUeFcWGPqcFpd1heJPj9%2Ffingerpush_fcm_-private_key_1.png?alt=media&amp;token=5a6ec556-90d9-4e10-a131-cdb70ccec6ef" alt=""><figcaption></figcaption></figure>

<div align="left"><figure><img src="https://1606198054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff5XCUiUhwc0T57hW21TH%2Fuploads%2FwBXnUnPSohbKCvsTZvhT%2Ffingerpush_fcm_%20private_key_2.png?alt=media&amp;token=ab70725a-3b0c-417a-8b21-4c8e1ff5e194" alt=""><figcaption></figcaption></figure> <figure><img src="https://1606198054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff5XCUiUhwc0T57hW21TH%2Fuploads%2FiRsBuBiPyajZ2EHLGs6P%2Ffingerpush_fcm_%20private_key_3.png?alt=media&amp;token=f6e4075d-7265-425e-9404-4038d4df3f39" alt=""><figcaption></figcaption></figure></div>

### SDK 적용하기

#### Gradle 설정

a. 프로젝트 레벨의 build.gradle 에 'com.google.gms:google-services' 라이브러리와 kotlin 라이브러리를 추가합니다.

{% code title="<project>/build.gradle" %}

```
buildscript {
    ...
    dependencies {
        ...
        classpath 'com.google.gms:google-services:4.4.3'
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:2.0.21"
    }
}
```

{% endcode %}

b. 앱 레벨의 build.gradle 하단에 google-services 플러그인을 추가합니다.

{% code title="<project>/<app-module>/build.gradle" %}

```
apply plugin: 'com.google.gms.google-services'
```

{% endcode %}

c. 다운받은 SDK 를 libs 폴더로 옮긴 뒤, 앱 레벨의 build.gradle 에 핑거푸시 SDK 및 firebase 모듈을 추가합니다.

{% code title="<project>/<app-module>/build.gradle" %}

```
dependencies {
    ...
    implementation files('libs/fingerpush_3.8.2.aar')
    implementation 'com.google.firebase:firebase-core:21.1.1'
    implementation 'com.google.firebase:firebase-messaging:24.1.2'
}
```

{% endcode %}

d. gradle.properties 파일에서 두 개의 플래그를 사용합니다.

{% code title="gradle.properties" %}

```
android.useAndroidX=true
android.enableJetifier=true
```

{% endcode %}

#### 핑거푸시 키 설정

a. Application class에서 핑거푸시 키를 설정합니다.

{% hint style="danger" %} <mark style="color:red;">앱키, 앱시크릿 변경시 기존 설정값들이 적용되지 않을 수 있기 때문에 앱 삭제 후 재설치를 권장드립니다.</mark>
{% endhint %}

```java
FingerPushManager.setAppKey(String appKey);
FingerPushManager.setAppSecret(String secretKey);
```

#### 알림 권한 추가 및 요청

Android 13(API Level33) 이상에서 알림 수신을 위해 권한 요청 및 허용되어야 합니다.

{% code title="AndroidManifest.xml" %}

```xml
<manifest ...>
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
    <application ...>
        ...
    </application>
</manifest>
```

{% endcode %}

{% code title="MainActivity.java" %}

```java
// 핑거푸시 단말기 등록 (앱 실행 시 매번 호출되어야 합니다.)
private void setDevice() {
    FingerPushManager.getInstance(this).setDevice(new NetworkUtility.ObjectListener() {
        @Override
        public void onComplete(String code, String message, JSONObject jsonObject) {
            // code 200, 201 단말기 등록.
        }

        @Override
        public void onError(String code, String message) {
            // code 504 단말기가 이미 등록됨.
        }
    });
}

// 알림 권한 요청 결과
private final ActivityResultLauncher<String> requestPermissionLauncher =
        registerForActivityResult(new ActivityResultContracts.RequestPermission(), isGranted -> {
            setDevice()
        });

// 알림 권한 요청
private void askNotificationPermission() {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) == PackageManager.PERMISSION_GRANTED) {
            // 이미 알림 권한이 허용된 상태
            setDevice();
        } else {
            // 사용자에게 알림 권한 요청
            requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS);
        }
    } else {
        setDevice();
    }
}
```

{% endcode %}

#### 채널 생성

{% hint style="danger" %}
Android 8(API Level 26) 이상은 Channel 을 생성해야 알림이 노출됩니다.

채널 생성은 앱을 시작할 때 생성하는게 안전합니다.

Channel 에 대한 상세 내용은 아래 주소를 참고바랍니다.
{% endhint %}

{% embed url="<https://developer.android.com/training/notify-user/channels>" %}

{% code title="MainActivity.java" %}

```java
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    String channelId  = getString(R.string.default_notification_channel_id);
    String channelName = getString(R.string.default_notification_channel_name);
    fingerNotification.createChannel(channelId, channelName);
}   
```

{% endcode %}

#### 알림 수신부

a. IntentService 클래스를 생성한 뒤, 'FingerPushFcmListener' 를 상속받습니다.

{% code title="IntentService.java" %}

```java
public class IntentService extends FingerPushFcmListener {
    @Override
    public void onMessage(Context context, Bundle data) {
        createNotification(data);
    }
}
```

{% endcode %}

b. onMessage(Context context, Bundle data) 에서 PayLoad 데이터를 확인할 수 있으며, 푸시 알림을 구현할 수 있습니다.

#### Payload 데이터

```
data.msgTag : 메세지 번호
data.code : CD:1;IM:0;PT:DEFT    <!-- (CD:커스텀데이터 여부(0없음, 1있음), IM:이미지여부(0없음, 1있음) ,PT:메세지타입 (DEFT:일반, LNGT:롱푸시, STOS:타겟푸시)  -->
data.time : 보낸시간
data.appTitle : 핑거푸시 앱이름
data.badge : 뱃지
data.sound : 사운드
data.title : 메세지 제목
data.message : 메세지내용
data.weblink : 웹링크 url
data.labelCode : 라벨코드
data.img : 이미지 여부            <!-- (0:없음;1:있음) -->
data.imgUrl : 이미지url
data.cd1 : 커스텀 데이터 
data.cd2 : 커스텀 데이터
data.cd3 : 커스텀 데이터
```

#### 알림 생성

기본 Notification 생성방법입니다.

{% code title="IntentService.java" %}

```java
private void createNotification(Bundle data) {
    NotificationManager mNotificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
        String channelId  = getString(R.string.default_notification_channel_id);
        String channelName = getString(R.string.default_notification_channel_name);
        
        NotificationChannel mChannel = new NotificationChannel(channelId, channelName, NotificationManager.IMPORTANCE_HIGH);
        mChannel.setDescription(null);
        mNotificationManager.createNotificationChannel(mChannel);
    }
 
    Intent intent = new Intent(IntentService.this, MainActivity.class);
    intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TASK | Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_SINGLE_TOP);
 
    PendingIntent pendingIntent;
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        pendingIntent = PendingIntent.getActivity(IntentService.this, (int) System.currentTimeMillis(), intent, PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_UPDATE_CURRENT);
    } else {
        pendingIntent = PendingIntent.getActivity(IntentService.this, (int) System.currentTimeMillis(), intent, PendingIntent.FLAG_CANCEL_CURRENT);
    }
 
    NotificationCompat.Builder mBuilder = new NotificationCompat.Builder(this)
        .setSmallIcon(R.mipmap.ic_launcher)
        .setContentTitle(data.getString("data.title"))
        .setContentText(data.getString("data.message"));
    mBuilder.setContentIntent(pendingIntent);
 
    mNotificationManager.notify((int) System.currentTimeMillis(), mBuilder.build());
}
```

{% endcode %}

핑거푸시에서 제공하는 Notification 생성 방법입니다.

{% code title="IntentService.java" %}

```java
private void createNotification(Bundle data) {
    Intent intent = new Intent(IntentService.this, MainActivity.class);
    intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TASK | Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_SINGLE_TOP);
 
    PendingIntent pendingIntent;
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        pendingIntent = PendingIntent.getActivity(IntentService.this, (int) System.currentTimeMillis(), intent, PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_UPDATE_CURRENT);
    } else {
        pendingIntent = PendingIntent.getActivity(IntentService.this, (int) System.currentTimeMillis(), intent, PendingIntent.FLAG_CANCEL_CURRENT);
    }
 
    FingerNotification fingerNotification = new FingerNotification(this);
    fingerNotification.setNotificationIdentifier((int) System.currentTimeMillis());
    fingerNotification.setIcon(R.drawable.m_ic_launcher);
    fingerNotification.setLargeIcon(BitmapFactory.decodeResource(getResources(), R.mipmap.ic_launcher));
    fingerNotification.setVibrate(new long[]{0, 500, 600, 1000});
    fingerNotification.setLights(Color.parseColor("#ffff00ff"), 500, 500);
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
        fingerNotification.setColor(Color.rgb(0, 114, 162));
    }
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
        String channelId  = getString(R.string.default_notification_channel_id);
        String channelName = getString(R.string.default_notification_channel_name);
        fingerNotification.createChannel(channelId, channelName);
    }                  
    fingerNotification.showNotification(data, pendingIntent);
}
```

{% endcode %}

c. FingerPush MessageID, MessageLabel, PushMode 값은 아래 함수를 통해 확인 가능합니다.

```java
String messageId = FingerPushManager.getMessageId(Bundle bundle);
String messageLabel = FingerPushManager.getMessageLabel(Bundle bundle);
String pushMode = FingerPushManager.getPushMode(Bundle bundle);
```

#### allowBackup 설정

a. allowBackup 값을 false 로 설정합니다.

{% code title="AndroidManifest.xml" %}

```
<application
    ...
    android:allowBackup="false"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name">
    ...
</application>
```

{% endcode %}

b. 푸시 수신을 서비스를 추가합니다.

{% code title="AndroidManifest.xml" %}

```xml
<manifest ...>
    ...
    <application ...>
        <service
            android:name=".IntentService"
            android:exported="false">
            <intent-filter>
                <action android:name="com.google.firebase.MESSAGING_EVENT" />
            </intent-filter>
        </service>
    </application>
</manifest>
```

{% endcode %}

{% hint style="info" %}
ProGuard를 사용하는 경우 룰을 추가합니다.
{% endhint %}

```
# For FingerPush SDK
-dontwarn com.fingerpush.**
```

### Android API Reference

Android API 는 아래 링크에서 확인 할 수 있습니다.

{% content-ref url="/pages/fx2bsLtt8TXjECxe6mfO" %}
[Android API Reference](/app-push/api-reference/android.md)
{% endcontent-ref %}

## API 연동 결과 코드

<table><thead><tr><th width="150">코드</th><th width="326">내용</th><th>비고</th></tr></thead><tbody><tr><td>200</td><td>정상 처리</td><td></td></tr><tr><td>403</td><td>App_key, secret오류, 권한 없음</td><td></td></tr><tr><td>404</td><td>조회 대상 없음, 조회 결과 없음</td><td></td></tr><tr><td>500</td><td>처리 중 에러</td><td></td></tr><tr><td>503</td><td>필수 값 없음</td><td></td></tr><tr><td>504</td><td>이미 등록된 토큰</td><td>디바이스 등록에서만 사용</td></tr></tbody></table>