# 2-1. 메시지 기본 정보 발송

### HTTPS Parameters

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

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

#### \[표 2.1] 다수 발송, 메시지 IDX 받기 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><p>보낼 푸시 메시지</p><p>통계 리스트에 표시됨</p></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>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>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 형태로 제공합니다. \
result 값이 200 이고, processCode가 20001 이면 다음 대상자 등록 프로세스를 진행합니다.

```json
{"result": "200", "msgIdx" :  "A1DS33DDSQ2321", "processCode" : "20001", "message" : "메시지 등록이 처리되었습니다. 발급받은 메시지 아이디로 대상자 등록을 시작해 주세요.", "ratelimit-limit" : "20", "ratelimit-remaining" : "17"}
```

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

<table><thead><tr><th width="150">값</th><th>설명</th></tr></thead><tbody><tr><td>result</td><td>결과 코드</td></tr><tr><td>msgIdx</td><td>메시지 번호</td></tr><tr><td>processCode</td><td>메시지 처리 단계</td></tr><tr><td>message</td><td>발송결과 메시지</td></tr><tr><td>ratelimit-limit</td><td>분당 허용되는 최대 요청 횟수</td></tr><tr><td>ratelimit-remaining</td><td>잔여 분(minute) 동안 가능한 요청 횟수</td></tr><tr><td>retry-after</td><td><p>요청 갱신 시간까지 남은 초(second)</p><p>- ratelimit를 초과한 경우에만 _code: 429와 함께 반환</p></td></tr></tbody></table>

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

<table><thead><tr><th width="204.00000000000003">코드</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><mark style="color:red;">4040</mark></td><td><mark style="color:red;">존재하지 않는 식별자</mark></td><td><p><mark style="color:red;">단일 건만 담겨 있는 경우.</mark></p><p><mark style="color:red;">존재하지 않거나 삭제된 식별자</mark></p></td></tr><tr><td>429</td><td>분당 호출 수 초과</td><td></td></tr><tr><td>500</td><td>서버 에러</td><td></td></tr><tr><td>503</td><td>필수 값이 누락됨</td><td>Message에 누락된 필수값 표시됨</td></tr><tr><td>504</td><td>발송 대상 처리 중 에러</td><td>발송 대상 데이터 확인</td></tr><tr><td>505</td><td>메시지 허용 byte 수 초과</td><td>1000 byte 제한</td></tr></tbody></table>

#### \[표 2.4] JSON 결과의 processCode code 유형

<table><thead><tr><th width="150">코드</th><th>내용</th><th>비고</th></tr></thead><tbody><tr><td>20001</td><td>푸시 메시지 등록 정상 처리</td><td>메시지 아이디가 반환됨</td></tr><tr><td>20002</td><td>발송대상자 등록 정상 처리</td><td> </td></tr><tr><td>20003</td><td>푸시 메시지 등록 완료</td><td> </td></tr></tbody></table>

JSON 형태로 제공되는 결과값 및 각 데이터의 코드값에 대한 설명은 [\[표 2.2\] 발송 JSON 결과](#2.2-json)와 [\[표 2.3\] 발송 JSON 결과의 result code 유형](#2.3-json-result-code)을 참조해 주시기 바랍니다.

### 샘플 소스 설명

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

JAVA용 샘플의 경우 Apache common의 HttpClient(<http://hc.apache.org/)를> 이용하여 파라미터를 전송하도록 하였으므로 해당 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", 푸시메시지 내용));                // 메시지(필수)
params.add (new BasicNameValuePair("isa", "Y"));           // 안드로이드를 사용하는 대상폰 발송 Y/N (필수)
params.add (new BasicNameValuePair("asnd", ""));           // 푸시 수신 시 안드로이드 사운드 (선택)
params.add (new BasicNameValuePair("abdg", ""));           // 안드로이드 푸시 배지 처리용(선택)
params.add (new BasicNameValuePair("isi", "Y"));           // IOS를 사용하는 대상폰 발송 Y/N(필수)
params.add (new BasicNameValuePair("ibdg", ""));           // IOS 푸시 배지 처리(선택)
params.add (new BasicNameValuePair("isnd", ""));           // 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("title", push.getTitle()));  // 제목
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("ofb_time", "1w"));      // opened fall back time: 오픈 처리 제한시간  - 2h, 4h, 1d, 3d, 5d, 1w
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","H"));    // 안드로이드 우선순위 H: 높음 / M: 중간(default)
params.add (new BasicNameValuePair("optagree", "0000"));    // 옵션 동의, 0000: 광고수신 비동의 여부에 관계없이 발송, 1000: 광고 수신 동의한 사람에게만 발송
```

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

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

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

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

```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();
```

4\) 받은 결과는 JSON 타입의 String 이므로 결과에 맞게 변환하여 사용하시는 UI에 적용하시면 됩니다.

```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();
```

5\) 해당 결과로 받은 내용을 JSON 형식으로 받아 파싱한 결과에 따라 다음 프로세스(대상자 발송)를 준비합니다.\
발송 결과가 result : 200, processCode : 20001인 경우, [\[표 2.2\] 발송 JSON 결과](#2.2-json)와 [\[표 2.3\] 발송 JSON 결과의 result code 유형](#2.3-json-result-code)을 참조해 주시기 바랍니다.

샘플 파일에서는 JSON형식의 String 문자열을 JSON Object 로 바꾸어 파싱하기 위해 sourceforge에서 배포하는 JSON-lib (<http://sourceforge.net/projects/json-lib/files/)를> 사용합니다.

```java
jsonString 
= sendMessage(strAppkey, strAppSecret, strCustomerKey, strMsg, callUrl);
JSONObject jsonObj = JSONObject.fromObject(jsonString);
    
String result = (String)jsonObj.get("result");              // 결과 코드
String msgIdx = (String)jsonObj.get("msgIdx");              // 메시지 등록 후 반환되는 메시지 번호
String processCode = (String)jsonObj.get("processCode");    // 메시지 발송 단계, 20001 메시지 등록 시작, 20002 대상자 설정, 20003 메시지 설정 완료
String message = (String)jsonObj.get("message");            // 반환된 결과 메시지
```

#### **PHP Version**

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

다수 발송의 첫 단계인 기본 메시지 발송의 부분은 앞서 설명한, 일괄 발송 및 단일 건 발송과 마찬가지로 필수값 및 메시지 부가 정보를 전송하는 것과 동일합니다.

&#x20;

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

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

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

```php
$option = array(
	"msg" 			=> "푸시 메시지2", 	// 메시지(필수)
	"isa" 			=> "Y",			// 안드로이드를 사용하는 대상폰 발송 Y/N
	"isi" 			=> "Y",			// IOS를 사용하는 대상폰 발송 Y/N
	"asnd" 			=> "",			// 푸시 수신 시 안드로이드 사운드 
	"abdg" 			=> "",			// 안드로이드 푸시 배지 처리용
	"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
	"title" 		=> "push",		// 제목
	"bgcolor" 		=> "#FF0000",	 	// 배경 컬러 RGB 값. ex) #FF0000
	"fcolor" 		=> "#4374D9",		// 폰트 컬러 RGB 값. ex) #4374D9
	"lcode" 		=> "",			// 메시지 라벨코드: 메시지 라벨관리에서 발급받은 10자리 난수
	"ofb_time" 		=> "1w",		// opened fall back time: 오픈 처리 제한시간 - 2h, 4h, 1d, 3d, 5d, 1w
	"isetiquette" 		=> "Y",			// 에티켓 시간 적용 여부 Y: 적용, N: 적용 안함
	"etiquette_stime" 	=> "20",		// 에티켓 적용 시작 시간 0~23
	"etiquette_etime" 	=> "8",			// 에티켓 적용 해제 시간 0~23
	"and_priority" 		=> "H",			// 안드로이드 우선순위 H: 높음 / M: 중간(default)
	"optagree" 		=> "0000",		// 옵션 
);
```

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/setSTSPushs.jsp](https://api-v2.fingerpush.com/rest/sts/v3/setSTSPushs.jsp)

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

```php
$url = ' https://api-v2.fingerpush.com/rest/sts/v4/setSTSPushs.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);                                        // 결과 값 출력
```

6\) 해당 결과로 받은 내용을 JSON 형식으로 받아 파싱한 결과에 따라 다음 프로세스(대상자 발송)를 준비합니다.&#x20;

발송 결과가 result : 200, processCode : 20001인 경우, [\[표 2.2\] 발송 JSON 결과](#id-2.2-json)와 [\[표 2.3\] 발송 JSON 결과의 result code 유형](#id-2.3-json-result-code)을 참조해 주시기 바랍니다.