Android SDK 매뉴얼

본 가이드는 Android Studio 21.1.1 기준으로 작성되었습니다.

SDK가 지원하는 최소 버전은 Android API 19(Kitkat) 이상입니다.

SDK 다운로드

1) SDK를 다운로드 합니다.

SDK 다운로드

FCM APP 생성

기존 GCM 프로젝트가 있는 경우, 반드시 기존 GCM 프로젝트를 추가해서 사용해야 합니다.

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

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

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

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

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

https://console.cloud.google.com/apisconsole.cloud.google.com

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

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

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

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

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

SDK 적용하기

Gradle 설정

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

<project>/build.gradle

buildscript {
    ext.kotlin_version = '1.8.10'
    ...
    
    dependencies {
        ...
        classpath 'com.google.gms:google-services:4.3.10'
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

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

<project>/<app-module>/build.gradle

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

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

<project>/<app-module>/build.gradle

dependencies {
    ...
    implementation files('libs/fingerpush_3.8.0.aar')
    implementation 'com.google.firebase:firebase-core:18.0.3'
    implementation 'com.google.firebase:firebase-messaging:23.0.6'
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version"
}

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

gradle.properties

android.useAndroidX=true
android.enableJetifier=true

핑거푸시 키 설정

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

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

알림 권한 추가 및 요청

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

AndroidManifest.xml

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

MainActivity.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();
    }
}

채널 생성

Android 8(API Level 26) 이상은 Channel 을 생성해야 알림이 노출됩니다.

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

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

Create and Manage Notification Channels  |  Android DevelopersAndroid Developers

MainActivity.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);
}   

알림 수신부

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

IntentService.java

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

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 생성방법입니다.

IntentService.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());
}

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

IntentService.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);
}

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

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

allowBackup 설정

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

AndroidManifest.xml

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

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

AndroidManifest.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>

ProGuard를 사용하는 경우 룰을 추가합니다.

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

Android API Reference

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

Android API Reference

API 연동 결과 코드

코드	내용	비고
200	정상 처리
403	App_key, secret오류, 권한 없음
404	조회 대상 없음, 조회 결과 없음
500	처리 중 에러
503	필수 값 없음
504	이미 등록된 토큰	디바이스 등록에서만 사용