# 1. 일괄 발송

## 개요 

일괄 발송 기능을 이용하여, 앱을 다운받은 사용자들을 대상으로 일괄적으로 푸시 메시지를 발송합니다.

이때, 해당 푸시 메시지를 수신할 수 있는 디바이스는 <mark style="color:blue;">앱을 삭제하지 않았고, 푸시 수신 체크가 활성화되어 있는 디바이스를 대상</mark>으로 합니다.

또한 예약 발송, 에티켓 타임 설정, 이미지 첨부(링크), Long text message, web link 및 Android/IOS API를 이용하여 푸시 수신 시의 사운드 및 배지 표시 기능 등을 제어할 수 있습니다.

![](https://1606198054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff5XCUiUhwc0T57hW21TH%2Fuploads%2FJFMSCZ0EGfInyTYe7fdR%2Fimage4.png?alt=media\&token=42fc5739-6f05-4982-a44f-b0d9634eab11)

{% hint style="info" %}
API Server URL: <https://api-v2.fingerpush.com/rest/sts/v4/setFingerPush.jsp>
{% endhint %}

## 발송 방법 및 전송/수신 파라미터 정의

### HTTPS Parameters

SSL Protocol을 이용하여 파라미터들을 핑거푸시 Server to Server API Server(이하 API Server)에 전달합니다.

필수 값을 제외한 옵션값들에 대해서는 파라미터가 전달되지 않을 경우 기본값으로 처리됩니다.

API Server로 전달해야 할 파라미터들은 아래 표를 참조해 주세요.<br>

#### \[표 1.1] 일괄 발송 HTTPS, Parameters

<table><thead><tr><th width="150">파라미터명</th><th width="150">필수 여부</th><th width="150">Byte 수</th><th>설명</th></tr></thead><tbody><tr><td><mark style="color:red;">appkey</mark></td><td>필수</td><td>-</td><td>Application key</td></tr><tr><td><mark style="color:red;">appsecret</mark></td><td>필수</td><td>-</td><td>Application Secret</td></tr><tr><td><mark style="color:red;">customerkey</mark></td><td>필수</td><td>-</td><td>Customer key</td></tr><tr><td><mark style="color:red;">msg</mark></td><td>필수</td><td>1000</td><td>보낼 푸시 메시지</td></tr><tr><td>isa</td><td>선택</td><td>-</td><td><p>Y: 안드로이드 기기 대상 발송(default) </p><p>N: 안드로이드 기기를 전송 대상에서 제외 </p><p>※ 해당 값이 빈 상태로 서버로 전달될 경우, 기본 값인 Y로 처리</p></td></tr><tr><td>asnd</td><td>선택</td><td>50</td><td><p>안드로이드 기기의 푸시 수신 사운드 </p><p>※ 핑거푸시 Android API 적용을 기준으로 효과음 지정</p></td></tr><tr><td>abdg</td><td>선택</td><td>-</td><td><p>안드로이드 푸시 배지 처리 파라미터, number type. ex) 1 ~ </p><p>※ 핑거푸시 Android API 적용을 기준으로 배지 효과 지정</p></td></tr><tr><td>isi</td><td>선택</td><td>1</td><td><p>Y: IOS 기기 대상 발송(default) </p><p>N: IOS 기기를 전송 대상에서 제외 </p><p>※ 해당 값이 빈 상태로 서버로 전달될 경우, 기본 값인 Y로 처리</p></td></tr><tr><td>ibdg</td><td>선택</td><td>-</td><td><p>IOS 푸시 배지 처리 파라미터, number type. ex) 1 ~ </p><p>※ 핑거푸시 IOS API 적용을 기준으로 배지 효과 지정</p></td></tr><tr><td>isnd</td><td>선택</td><td>50</td><td><p>IOS 기기의 푸시 수신 사운드 </p><p>※ 핑거푸시 IOS API 적용을 기준으로 효과음 지정</p></td></tr><tr><td>ck1</td><td>선택</td><td>100</td><td><p>커스텀 키 1(App 개발 시 반영된 값) </p><p>deep link > app link > custom key 1 </p><p>※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 값</p></td></tr><tr><td>ck2</td><td>선택</td><td>100</td><td><p>커스텀 키 2(App 개발 시 반영된 값) </p><p>deep link > app link > custom key 2 </p><p>※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 값</p></td></tr><tr><td>ck3</td><td>선택</td><td>100</td><td><p>커스텀 키 3(App 개발 시 반영된 값) </p><p>deep link > app link > custom key 3 </p><p>※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 값</p></td></tr><tr><td>cv1</td><td>선택</td><td>200</td><td><p>커스텀 값 1(App 개발 시 반영된 값) </p><p>deep link > app link > custom value 1 </p><p>※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 매칭 값</p></td></tr><tr><td>cv2</td><td>선택</td><td>200</td><td><p>커스텀 값 2(App 개발 시 반영된 값) </p><p>deep link > app link > custom value 2 </p><p>※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 매칭 값</p></td></tr><tr><td>cv3</td><td>선택</td><td>200</td><td><p>커스텀 값 3(App 개발 시 반영된 값) </p><p>deep link > app link > custom value 3 </p><p>※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 매칭 값</p></td></tr><tr><td>link</td><td>선택</td><td>200</td><td><p>deep link > web link<br>ex) https://www.kissoft.co.kr </p><p>※ 해당 링크에 정의된 값이 있으면 푸시 메시지에 해당 링크 제공(핑거푸시 APP API가 적용되어 있어야 함)</p></td></tr><tr><td>fnm</td><td>선택</td><td>256</td><td><p>첨부 이미지 링크</p><p>-안드로이드 폰에서 첨부된 이미지 표현 가능</p><p>-도메인을 포함한 전체 경로 입력 </p><p>ex)http://www.kissoft.co.kr/images/img.jpg</p></td></tr><tr><td>mode</td><td>선택</td><td>-</td><td><p>DEFT: 일반 푸시(default) LNGT: long text push </p><p>※ 해당 값을 서버로 전송하지 않으면 일반 푸시 처리됨</p></td></tr><tr><td>lngt_message</td><td>선택</td><td>Text</td><td><p>Long text message 내용</p><p>-길이에 제약이 없는 long text message를 처리하기 위한 값</p><p>-해당 내용에는 HTML tag 포함 가능, Script 등은 사용 불가</p><p>-해당 기능을 사용하기 위해서는 mode 값이 LNGT로 설정되어야 함</p></td></tr><tr><td>send_state</td><td>선택</td><td>4</td><td><p>0001: 바로 발송(default) </p><p>0002: 예약발송</p></td></tr><tr><td>senddate</td><td>선택</td><td>12</td><td><p>send_stat 값이 0002(예약발송)으로 처리된 경우 예약 발송 날자 및 시간 입력 </p><p>ex) yyyymmdd24hmin -> 202109172113</p></td></tr><tr><td>tag</td><td>선택</td><td>-</td><td><p>태그 발송</p><p>-App 개발 시 적용한 tag 값을 기준으로 메시지 발송 시 tag를 지정하여 발송</p><p>-여러 개의 태그 적용 시 콤마( , )로 구분, 해당 태그들은 OR 조건으로 발송됨 </p><p>ex) 서울,대전,대구,부산</p></td></tr><tr><td>beschmode</td><td>선택</td><td>-</td><td><p>태그 발송 시 조건 </p><p>0001: or(default) </p><p>0002: and</p></td></tr><tr><td>title</td><td>선택</td><td>100</td><td>푸시 수신 시 메시지 제목</td></tr><tr><td>lcode</td><td>선택</td><td>10</td><td>라벨 코드</td></tr><tr><td>bgcolor</td><td>선택</td><td>7</td><td>배경색 ex) #FFFFFF</td></tr><tr><td>fcolor</td><td>선택</td><td>7</td><td>폰트 색상 ex) #000000</td></tr><tr><td>isetiquette</td><td>선택</td><td>-</td><td><p>에티켓 시간 적용 여부 </p><p>Y: 적용(default) </p><p>N: 적용 안함</p></td></tr><tr><td>etiquette_stime</td><td>선택</td><td>-</td><td><p>에티켓 적용 시작시간 </p><p>-Number type(1~ 24) </p><p>-default: 21(오후 9시)</p></td></tr><tr><td>etiquette_etime</td><td>선택</td><td>-</td><td><p>에티켓 적용 종료시간 </p><p>-Number type(1~24)<br>-default: 8(오전 8시)</p></td></tr><tr><td>and_priority</td><td>선택</td><td>-</td><td><p>안드로이드용 메시지 우선순위 </p><p>H: 높음 </p><p>M: 중간(default)</p></td></tr><tr><td>optagree</td><td>선택</td><td>-</td><td><p>0000: 광고 수신 동의 여부에 관계없이 푸시 수신자 모두에게 발송(default) </p><p>1000: 광고 수신 동의한 디바이스에만 메시지 발송</p></td></tr></tbody></table>

### Response JSON

API 서버에서 전달 받은 파라미터 처리 후 결과를 JSON 형태로 제공합니다.

```json
{"result" : "200", "message" : "정상 처리되었습니다.",  "msg_idx" : "DEF_3342131",  "tokenCnt" : "15"}
```

#### \[표 1.2] 발송 JSON 결과

<table><thead><tr><th width="150">값</th><th>설명</th></tr></thead><tbody><tr><td>result</td><td>결과 코드</td></tr><tr><td>message</td><td>결과 메시지</td></tr><tr><td>msg_idx</td><td><p>등록된 메시지 번호. 결과 조회 시 사용 </p><p>ex) DEF_40213134</p></td></tr><tr><td>tokenCnt</td><td>발송 대상 디바이스(모바일기기) 수</td></tr></tbody></table>

처리결과에 따른 result 값은 아래와 같습니다.

#### \[표 1.3] 발송 JSON 결과의 result code 유형

<table><thead><tr><th width="150">코드</th><th>내용</th><th>비고</th></tr></thead><tbody><tr><td>200</td><td>정상처리 됨</td><td> </td></tr><tr><td>4031</td><td>유효하지 않은 appkey 혹은 appsecret</td><td> </td></tr><tr><td>4032</td><td>Server to Server 서비스 이용권한 없음</td><td> </td></tr><tr><td>500</td><td>처리 중 오류 발생</td><td>발송 대상자, 메시지</td></tr><tr><td>503</td><td>필수 값이 누락됨</td><td>Message에 누락된 필수값 표시됨</td></tr></tbody></table>

## 샘플 소스 설명

HTTPS로 미리 정의된 파라미터들을 전달하고 JSON으로 결과 데이터를 읽을 수 있도록 작업해 주시면 됩니다.

JAVA용 샘플의 경우 Apache common의 HttpClient(<http://hc.apache.org/)를> 이용하여 파라미터를 전송하도록 하였으므로 해당 library가 필요합니다. 해당 기능만 충족하면 되므로 여타 다른 library를 사용하셔도 무방합니다. 샘플 소스는 GitHub를 통해 확인 가능합니다.&#x20;

JSP 샘플의 경우, 샘플 메소드를 이용한 직접 발송이 가능합니다. 혹, 사용자 환경에 맞도록 수정이 필요하면 class(com.fingerpush.push.FingerpushDaoImpl) 내에 구성되어 있는 메소드를 참조해 주시기 바랍니다.

해당 샘플에 대한 설명은 파라미터 전달 및 API URL에 대해 클래스 내에 구현되어 있는 로직 위주로 설명 드립니다.

### JAVA Version

Github에 올려져 있는 샘플 소스는 아래 설명된 내용 중 중복된 부분들을 method화 하여 처리하므로 약간의 차이가 있을 수 있으나, 기본 발송 방식의 설명이므로 해당 중복되는 부분을 풀어서 설명하도록 하겠습니다.

1\) 파라미터를 담을 List 객체를 선언해 전달할 값들을 셋팅 합니다.

```java
List <BasicNameValuePair> params = new ArrayList<BasicNameValuePair>();
```

2\) 필수 값들을 셋팅 합니다.

```java
List <BasicNameValuePair> params = new ArrayList<BasicNameValuePair>(); 

params.add (new BasicNameValuePair("appkey", 애플리케이션 키));            // (필수)	
params.add (new BasicNameValuePair("appsecret", 애플리케이션 시크릿));      // (필수)
params.add (new BasicNameValuePair("customerkey", 발급받은 커스터머키));    // (필수)
params.add (new BasicNameValuePair("msg", 푸시메시지 내용));               // 푸시메시지 내용(필수)
```

3\) 선택 값들을 셋팅 합니다. (선택)

* 해당 내용들은 Application 개발 시 반영된 내용을 기준으로 처리합니다.
* 2.5 버전부터 새로 추가된 내용들에 대해서도 값들을 추가합니다.
* 해당 내용들은 안드로이드 및 IOS용 SDK가 앱에 적용되어 있어야만 기능이 발현됩니다.

```java
params.add (new BasicNameValuePair("isa", "Y"));       // 안드로이드를 사용하는 대상 폰 발송 Y/N(선택)
params.add (new BasicNameValuePair("asnd", "ring1"));  // 푸시 수신 시 안드로이드 사운드(선택)
params.add (new BasicNameValuePair("abdg", "1"));      // 안드로이드 푸시 배지 처리용(선택)        
params.add (new BasicNameValuePair("isi", "Y"));       // IOS를 사용하는 대상 폰 발송 Y/N (선택)
params.add (new BasicNameValuePair("ibdg", "1"));      //IOS 푸시 배지 처리(선택)
params.add (new BasicNameValuePair("isnd", "ring1"));  // IOS 푸시 사운드 처리(선택)        
params.add (new BasicNameValuePair("ck1", ""));        // custom key 1(선택)
params.add (new BasicNameValuePair("ck2", ""));        // custom key 2(선택)
params.add (new BasicNameValuePair("ck3", ""));        // custom key 3(선택)
params.add (new BasicNameValuePair("cv1", ""));        // custom value 1(선택)
params.add (new BasicNameValuePair("cv2", ""));        // custom value 2(선택)
params.add (new BasicNameValuePair("cv3", ""));        // custom value 3(선택)
params.add (new BasicNameValuePair("fnm", ""));        // 첨부이미지 파일 링크 경로(선택)
params.add (new BasicNameValuePair("tag", "서초,강남,송파"));  // 첨부이미지 파일 링크 경로(선택)
params.add (new BasicNameValuePair("beschmode", "0001"));     // 0001: or(default), 0002: and
params.add (new BasicNameValuePair("title", "앱 업데이트 공지"));  // 제목
params.add (new BasicNameValuePair("bgcolor", "#FF0000"));   // 배경 컬러 RGB 값. ex) #FF0000
params.add (new BasicNameValuePair("fcolor", "#4374D9"));    // 폰트 컬러 RGB 값. ex) #4374D9
params.add (new BasicNameValuePair("lcode", ""));            // 메시지 라벨코드 : 메시지 라벨관리에서 발급받은 10자리 난수
params.add (new BasicNameValuePair("isetiquette", "Y"));     // 에티켓 시간 적용 여부 Y:적용, N: 적용 안함
params.add (new BasicNameValuePair("etiquette_stime", "20"));   // 에티켓 적용 시작 시간 0~23
params.add (new BasicNameValuePair("etiquette_etime", "8"));    // 에티켓 적용 해제 시간 0~23
params.add (new BasicNameValuePair("and_priority", "M"));  // 안드로이드 우선순위 H: 높음 / M: 중간(default)
params.add (new BasicNameValuePair("optagree", "0000"));   // 0000: 광고수신 비동의 여부에 관계없이 발송, 1000: 광고수신 동의 한 사람에게만 발송
```

4\) 기존 HttpClient의 DefaultHttpClient를 이용한 원격 접속 방식이 deprecated 된 이유로 HttpsURLConnection을 이용하여 접속합니다. 물론 deprecated 되었다고 해서 DefaultHttpClient 방식이 동작하지 않는 것은 아닙니다. 해당 방식 역시 github에 올려져 있는 샘플 소스에 구현되어 있습니다.

* 예제: FingerpushDaoImpl.sendHttpsExe(String callUrl, List \<BasicNameValuePair> params)

전달하는 파라미터는 UTF-8로 인코딩 하여 전달해야 합니다.

* 예제: 샘플의 FingerpushDaoImpl.sendHttpsUrlConExe(String callUrl, List \<BasicNameValuePair> params)

{% hint style="info" %}
API Server URL: [https://api-v2.fingerpush.com/rest/sts/v4/setFingerPush.jsp](https://api-v2.fingerpush.com/rest/sts/v3/setFingerPush.jsp)
{% endhint %}

```java
URL url = new URL(callUrl);
trustAllHosts();

HttpsURLConnection httpsURLConnection = (HttpsURLConnection) url.openConnection();
httpsURLConnection.setHostnameVerifier(new HostnameVerifier() {
    @Override
    public boolean verify(String s, SSLSession sslSession) {
        return true;
    }
});
HttpURLConnection connection = httpsURLConnection;

connection.setRequestMethod("POST");
connection.setUseCaches(false);           
connection.setDoInput(true);
connection.setDoOutput(true);

UrlEncodedFormEntity entity = new UrlEncodedFormEntity(params, "utf-8");
OutputStream post = connection.getOutputStream();
entity.writeTo(post);
 
post.flush();
connection.connect();
```

5\) 받은 결과는 JSON 타입의 String이므로 결과에 맞게 변환하여 사용하시는 UI에 적용하시면 됩니다. 받은 jsonString은 앞서 설명한 '[Response JSON](#response-json)' 부분을 참조해 주세요.

```java
StringBuilder responseStringBuilder = new StringBuilder();
logger.debug("contentType : "+connection.getContentType());
if (connection.getResponseCode() == HttpURLConnection.HTTP_OK){
    BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(connection.getInputStream(), "UTF-8"));
    for (;;){
        String stringLine = bufferedReader.readLine();
        if (stringLine == null ) break;
        responseStringBuilder.append(stringLine + '\n');
    }
    bufferedReader.close();
}
connection.disconnect();
jsonString = responseStringBuilder.toString();
```

#### ※ JAVA Version 일괄발송 샘플

<table data-header-hidden><thead><tr><th width="150"></th><th></th></tr></thead><tbody><tr><td>소스 주소</td><td><a href="https://github.com/kissoft/FingerPushSTSinJava">https://github.com/kissoft/FingerPushSTSinJava</a></td></tr><tr><td>class</td><td><p>com.fingerpush.push.FingerpushDao</p><p>com.fingerpush.push.FingerpushDaoImpl</p><p>com.fingerpush.push.PushVO</p></td></tr><tr><td>jsp</td><td>JSP/sendAllDevice.jsp</td></tr></tbody></table>

###

### PHP Version

Github에 올려져 있는 샘플 소스는 아래 설명된 내용 중 중복된 부분들을 method화 하여 처리하므로 약간의 차이가 있을 수 있으나, 기본 발송 방식의 설명이므로 해당 중복되는 부분을 풀어서 설명하도록 하겠습니다.

1\) 기본 앱 정보를 세팅합니다.

```php
// 공통 필수 
$key = array(
    'appkey'            => '[발급받은 appkey]',
    'appsecret'         => '[발급받은 appsecret]',
    'customerkey'       => '[발급받은 customerkey]',
);
```

2\) 메시지 발송에 사용되는 필수값과 선택값을 세팅합니다.

```php
// (필수) 표기를 제외한 항목은 모두 선택사항
$option = array(
    "msg"               => "전체 메시지", // 메시지(필수)
    "isa"               => "Y",         // 안드로이드를 사용하는 대상폰 발송 Y/N
    "abdg"              => "",          // 안드로이드 푸시 배지 처리 용
    "asnd"              => "",          // 푸시 수신 시 안드로이드 사운드
    "isi"               => "Y",         // IOS를 사용하는 대상폰 발송 Y/N
    "ibdg"              => "",          // IOS 푸시 배지 처리
    "isnd"              => "",          // IOS 푸시 사운드 처리 
    "ck1"               => "",          // custom key 1
    "ck2"               => "",          // custom key 2
    "ck3"               => "",          // custom key 3
    "cv1"               => "",          // custom value 1
    "cv2"               => "",          // custom value 2
    "cv3"               => "",          // custom value 3
    "fnm"               => "",          // 첨부이미지 파일 링크 경로
    "link"              => "",          // 링크 URL
    "mode"              => "DEFT",      // DEFT: 일반 푸시 메시지 / LNGT: 내용이 많은 long text push
    "lngt_message"      => "",          // long text message
    "send_state"        => "0001",      // 0001: 바로 발송 / 0002: 예약발송
    "senddate"          => "",          // 예약발송인 경우 예약 발송일 ex) 202109172113
    "tag"               => "",          // 발송 tag. 쉼표(, )로 구분. ex) 서울,대전,대구,부산
    "beschmode"         => "0001",      // 태그 발송 시 조건. 0001: or / 0002: and
    "title"             => "",          // 제목
    "bgcolor"           => "#FFFFFF",   // 배경 컬러
    "fcolor"            => "#4374D9",   // 폰트 컬러
    "lcode"             => "",          // 메시지 라벨코드 : 메시지 라벨관리에서 발급받은 10자리 난수
    "isetiquette"       => "Y",         // 에티켓 시간 적용 여부 Y 적용, N 적용 안함.
    "etiquette_stime"   => "20",        // 에티켓 적용 시작 시간 0~23
    "etiquette_etime"   => "8",         // 에티켓 적용 해제시간 0~23
    "and_priority"      => "M",         // 안드로이드 우선순위 H: 높음 / M: 중간(default)
    "optagree"          => "0000",      // 옵션 동의. 0000: 광고수신 비동의 여부에 관계없이 발송, 1000: 광고수신 동의 한 사람에게만 발송
);
```

3\) 앱 기본정보와 옵션값을 URL 인코드 한 쿼리 문자열로 생성합니다.

```php
$data = array_merge ( $key, $option ); 	         // 세팅한 데이터를 하나의 배열로 합칩니다.
$param = http_build_query ($data); 	         // 파라미터를 생성합니다.
```

4\) PHP cURL 라이브러리를 이용하여 핑거푸시 API와 통신합니다.

* PHP Curl 라이브러리: <https://www.php.net/manual/en/book.curl.php>
* 다수에게 메시지 발송 API URL: <https://api-v2.fingerpush.com/rest/sts/v4/setFingerpush.jsp>

cURL을 아래와 같이 HTTPS 통신으로 세팅합니다.

```php
$url = ' https://api-v2.fingerpush.com/rest/sts/v4/setFingerPush.jsp'; // 핑거푸시 다수에게 메시지 발송 API URL
$ch = curl_init (); 			                // cURL 선언
curl_setopt ( $ch, CURLOPT_URL, $url ); 		// URL 세팅
curl_setopt ( $ch, CURLOPT_SSL_VERIFYPEER, false ); 	// 인증서 체크
curl_setopt ( $ch, CURLOPT_SSLVERSION, 1 ); 	        // SSL 버전 -> 1만 된다.
curl_setopt ( $ch, CURLOPT_HEADER, 0 ); 		// 헤더 출력 여부
curl_setopt ( $ch, CURLOPT_POST, 1 ); 			// POST, GET 접속 여부
curl_setopt ( $ch, CURLOPT_TIMEOUT, 30 ); 		// Time Out 세팅
curl_setopt ( $ch, CURLOPT_RETURNTRANSFER, 1 );         // 결과값 리턴 여부
curl_setopt ( $ch, CURLOPT_POSTFIELDS, $param );         // parameter
$res = curl_exec ( $ch ); 								// cURL 실행하고 결과 저장

/* cURL 에러검출 */
$cErrno = curl_errno ( $ch );

if ($cErrno == 0) $response = $res;
else $response = exit;
curl_close ( $ch ); 			                 // cURL을 닫고 자원 반환
```

5\) 전달 받은 JSON 문자열 결과값을 PHP 변수로 변환합니다.

```php
// 1. json 처리시
echo $response;

// 2. object 처리시
$result = json_decode ( $response, true );              // 결과값 JSON 디코드
print_r($result);
```