4. 다수의 대상자 개별 설정값 발송

개요

기존, 다수의 타겟팅 된 대상자에게 메시지를 전송하는 상황(2. 다수의 대상자 발송)에서 별도의 설정 값을 추가하여 처리하는 방법입니다.

해당 기능을 이용할 경우 기존 개별 발송이 가능한 내용(메시지, 링크, 이미지경로, 타이틀) 외에 (커스텀키1~3, 커스텀값1~3, 라벨코드, 안드로이드 우선순위) 값을 추가로 발송할 수 있습니다.

기존 다수의 대상자에게 다른 메시지 전송 방법과 동일하며 메시지 내역에 JSON 형태로 메시지 및 설정 값을 등록하여 발송하게 됩니다.

해당 API는' 2. 다수의 대상자 발송’을 기반으로 처리되고 있으므로 앞선 매뉴얼을 먼저 숙지하시길 권고 드립니다.

1) 기본 메시지 정보를 발송하고 메시지 IDX를 수신합니다.

2) 수신 받은 메시지 IDX와 푸시 메시지를 받을 대상자 및 메시지, 기타 개별 정보를 전송합니다. (반복)

3) 수신 받은 메시지 IDX와 푸시 메시지 정보 전달 종료 플래그를 전송합니다.

API Server URL: https://api-v2.fingerpush.com/rest/sts/v4/setSTSJsonPushs.jsp

메시지 기본 정보 발송

HTTPS Parameters

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

API Server로 전달해야 할 파라미터들은 아래 표를 참조해 주세요. 해당 내용은 '2. 다수의 대상자 발송'의 내용을 기본으로 하고 있으나 개별 설정 값의 경우는 메시지 내용에 JSON 형태로 입력되므로 빈 상태로 전달되게 됩니다.

[표 3.1] 다수 발송 메시지 IDX 받기 HTTPS, Parameters

파라미터명	필수 여부	Byte 수	설명
appkey	필수	-	Application key
appsecret	필수	-	Application Secret
customerkey	필수	-	Customer key
msg	필수	1000	보낼 푸시 메시지 해당 내용은 리스트상에 표시되는 대표 메시지이므로 JSON 형태로 입력하지 않습니다.
isa	선택	-	Y: 안드로이드 기기 대상 발송(default) N: 안드로이드 기기를 전송 대상에서 제외 ※ 해당 값이 빈 상태로 서버로 전달될 경우, 기본 값인 Y로 처리
asnd	선택	50	안드로이드 기기의 푸시 수신 사운드 ※ 핑거푸시 Android API 적용을 기준으로 효과음 지정
abdg	선택	-	안드로이드 푸시 배지 처리 파라미터, number type. ex) 1 ~ ※ 핑거푸시 Android API 적용을 기준으로 배지 효과 지정
isi	선택	1	Y: IOS 기기 대상 발송(default) N: IOS 기기를 전송 대상에서 제외 ※ 해당 값이 빈 상태로 서버로 전달될 경우, 기본 값인 Y로 처리
ibdg	선택	-	IOS 푸시 배지 처리 파라미터, number type. ex) 1 ~ ※ 핑거푸시 IOS API 적용을 기준으로 배지 효과 지정
isnd	선택	50	IOS 기기의 푸시 수신 사운드 ※ 핑거푸시 IOS API 적용을 기준으로 효과음 지정
send_state	선택	4	0001: 바로 발송(default) 0002: 예약발송
senddate	선택	12	send_stat 값이 0002(예약발송)으로 처리된 경우 예약 발송 날자 및 시간 입력 ex) yyyymmdd24hmin -> 202109172113
bgcolor	선택	7	배경색 ex) #FFFFFF
fcolor	선택	7	폰트 색상 ex) #000000
isetiquette	선택	-	에티켓 시간 적용 여부 Y: 적용(default) N: 적용 안함
etiquette_stime	선택	-	에티켓 적용 시작시간 -Number type(1~ 24) -default: 21(오후 9시)
etiquette_etime	선택	-	에티켓 적용 종료시간 -Number type(1~24) -default: 8(오전 8시)
optagree	선택	-	0000: 광고 수신 동의 여부에 관계없이 푸시 수신자 모두에게 발송(default) 1000: 광고 수신 동의한 디바이스에만 메시지 발송

Response JSON

API 서버에서 전달받은 파라미터 처리 후 결과를 JSON 형태로 제공합니다. result 값이 200 이고, processCode가 20001 이면 다음 대상자 등록 프로세스를 진행합니다.

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

[표 3.2] 발송 JSON 결과

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

[표 3.3] 발송 JSON 결과의 result code 유형

코드	내용	비고
200	정상처리 됨
4031	유효하지 않은 appkey 혹은 appsecret
4032	Server to Server 서비스 이용권한 없음
4040	존재하지 않는 식별자	단일 건만 담겨 있는 경우. 존재하지 않거나 삭제된 식별자
429	분당 호출 수 초과
500	서버 에러
503	필수 값이 누락됨	Message에 누락된 필수값 표시됨
504	발송 대상 처리 중 에러	발송 대상 데이터 확인
505	메시지 허용 byte 수 초과	1000 byte 제한

[표 3.4] JSON 결과의 processCode code 유형

코드	내용	비고
20001	푸시 메시지 등록 정상 처리	메시지 아이디가 반환됨
20002	발송대상자 등록 정상 처리
20003	푸시 메시지 등록 완료

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

샘플 소스 설명

해당 내용은 ‘2. 다수의 대상자 발송 > 메시지 기본 정보 발송 > 샘플 소스 설명’을 참조해 주세요.

수신 대상자 정보 및 개별 설정값 발송

HTTPS Parameters

앞서 메시지 정보를 보내고 해당 메시지에 대한 IDX를 얻었다면, 보내야 할 대상자들을 500개 한 묶음으로 메시지 IDX와 함께 API서버로 SSL Protocol을 이용하여 파라미터들을 API Server에 전달합니다. ('메시지 기본 정보 발송' 참조)

개별 설정값은 개별 메시지와 더불어 JSON 형태로 메시지(msg) 파라미터에 포함됩니다. API Server로 전달해야 할 파라미터 들은 아래 표를 참조해 주세요.

[표 3.5] 다수 발송 메시지 HTTPS, Parameters

파라미터명	필수 여부	Byte 수	설명
appkey	필수	-	Application key
appsecret	필수	-	Application Secret
customerkey	필수	-	Customer key
msgidx	필수	-	메시지를 셋팅하고 돌려받은 메시지 idx 값
identity	필수	50	메시지를 받을 대상자(500건 이하로 입력)
message	필수	4000	대상자에게 보낼 메시지 및 설정값을 JSON 형식의 Text로 전달(500건 이하로 입력)
prv_attachfname	선택	256	대상자에게 보낼 이미지(500건 이하로 입력)
prv_linkurl	선택	256	대상자에게 보낼 웹링크(500건 이하로 입력)
prv_title	선택	100	대상자에게 보낼 제목(500건 이하로 입력)

Response JSON

API서버에서 전달받은 파라미터 처리 후 결과를 JSON 형태로 제공합니다. 만일 발송 대상이 남아 있다면, 해당 결과 수신 후 남은 대상자에 따라 몇 회에 걸쳐 수신 대상자 목록을 발송합니다. (한번에 최대 500건 단위)

{"result" : "200", "msgIdx" :  "A1DS33DDSQ2321", "processCode" : "20002", "message" : "대상자 등록이 처리되었습니다. 대상자를 계속 등록하실 수도, 메시지 등록을 완료하실 수도 있습니다."}

JSON 형태로 제공되는 결과 값 및 각 데이터의 코드값에 대한 설명은 [표 3.3] 발송 JSON 결과의 result code 유형과 [표 3.4] JSON 결과의 processCode code 유형을 참조해 주시기 바랍니다.

개별 설정값이 적용되는 메시지 유형 설명(JSON Text)

개별 발송 메시지에 개별 설정값을 포함한 JSON 형식의 text 문장으로 처리됩니다. 해당 JSON 형식에 문법적 오류가 있다면, 발송 서버에서는 오류로 처리하게 됩니다. API 호출 경로가 기존 ‘6. 다수의 대상자에게 다른 메시지 발송’과 다르므로 확인해 주셔야 합니다.

API SERVER URL: https://api-v2.fingerpush.com/rest/sts/v4/setSTSJsonPushs.jsp

해당 JSON에 포함되는 항목은 아래와 같습니다.

[표 3.6] JSON 메시지 내용

파라미터명	필수 여부	Byte 수	설명
message	필수	1000	개별 메시지
ck1	선택	100	커스텀 키 1(App 개발 시 반영된 값) deep link > app link > custom key 1 ※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 값
ck2	선택	100	커스텀 키 2(App 개발 시 반영된 값) deep link > app link > custom key 2 ※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 값
ck3	선택	100	커스텀 키 3(App 개발 시 반영된 값) deep link > app link > custom key 3 ※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 값
cv1	선택 (ck1 값이 있는 경우 필수)	200	커스텀 값 1(App 개발 시 반영된 값) deep link > app link > custom value 1 ※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 매칭 값
cv2	선택 (ck2 값이 있는 경우 필수)	200	커스텀 값 2(App 개발 시 반영된 값) deep link > app link > custom value 2 ※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 매칭 값
cv3	선택 (ck3 값이 있는 경우 필수)	200	커스텀 값 3(App 개발 시 반영된 값) deep link > app link > custom value 3 ※ 핑거푸시 API 적용을 기준으로 사용자가 정의한 키 매칭 값
lcode	선택	10	라벨 코드
and_priority	선택	-	안드로이드용 메시지 우선순위 H: 높음 M: 중간(default)

※ 메시지 JSON 예

{
"message":"개별 메시지 내용입니다"
 ,"ck1":" 커스텀 키1"
 ,"ck2":" 커스텀 키2"
 ,"ck3":" 커스텀 키3"
 ,"cv1":"커스텀 값1"
 ,"cv2":"커스텀 키 값2"
 ,"cv3":"커스텀 키 값3"
 ,"lcode":"메시지라벨코드"
 ,"and_priority": "H"
}

샘플 소스 설명

‘2. 다수의 대상자 발송 > 수신 대상자 정보 발송 > 샘플 소스 설명’을 참조해 주세요 발송 방법은 동일하며 메시지 내용만 JSON으로 작성하여 추가해 주시면 됩니다.

JAVA Version

1) 푸시를 받을 대상자 및 메시지(JSON text 형식), 그 외 설정값들을 셋팅 합니다. 한 번에 보내는 대상자는 500건 이하로 해야 합니다.

… …
JsonObject msg_n = new JsonObject();
msg_n.put("message", "n 번째 메시지");
msg_n.put("lcode", "Esd23faae1");
msg_n.put("ck1", "");
msg_n.put("ck2", "");
msg_n.put("ck3", "");
msg_n.put("cv1", "");
msg_n.put("cv2", "");
msg_n.put("cv3", "");
msg_n.put("and_priority", "H");

params.add (new BasicNameValuePair("identity", 수신받을 대상자의 식별자1));   // (필수)
params.add (new BasicNameValuePair("message",msg_1.toJSONString()));        // JSON 형식의  보낼 메시지 및 설정값1(필수)
params.add (new BasicNameValuePair("prv_attachefname", 수신받을 대상자에게 보낼 이미지1));  // (선택)
params.add (new BasicNameValuePair("prv_linkurl", 수신받을 대상자에게 보낼 웹링크1));  // (선택)
params.add (new BasicNameValuePair("prv_title", 수신받을 대상자에게 보낼 제목1));      // (선택)
params.add (new BasicNameValuePair("identity", 수신받을 대상자의 식별자2));           // (필수)
params.add (new BasicNameValuePair("message", msg_2.toJSONString()));             // JSON 형식의  보낼 메시지 및 설정값2(필수)
params.add (new BasicNameValuePair("prv_attachefname", 수신받을 대상자에게 보낼 이미지2));  // (선택)
params.add (new BasicNameValuePair("prv_linkurl", 수신받을 대상자에게 보낼 웹링크2));  // (선택)
params.add (new BasicNameValuePair("prv_title", 수신받을 대상자에게 보낼 제목2));      // (선택)
… 중략 …
params.add (new BasicNameValuePair("identity", 수신받을 대상자의 식별자n));           // (필수)
params.add (new BasicNameValuePair("message",msg_n.toJSONString()));              // JSON 형식의  보낼 메시지 및 설정값 n(필수)
Params.add (new BasicNameValuePair("prv_attachefname", 수신받을 대상자에게 보낼 이미지n));  // (선택)
params.add (new BasicNameValuePair("prv_linkurl", 수신받을 대상자에게 보낼 웹링크n));  // (선택)
params.add (new BasicNameValuePair("prv_title", 수신받을 대상자에게 보낼 제목n));      // (선택)
… …

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

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

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

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

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

3) 받은 결과는 JSON 타입의 String 이므로 결과에 맞게 변환하여 사용하시는 UI에 적용하시면 됩니다. [표 3.2] 발송 JSON 결과와 [표 3.3] 발송 JSON 결과의 result code 유형을 참조해 주시기 바랍니다.

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

4) 해당 결과로 받은 내용을 JSON형식으로 받아 파싱한 결과에 따라 다음 프로세스(대상자 발송)를 준비합니다. 샘플 파일에서는 JSON형식의 String 문자열을 JSON Object 로 바꾸어 파싱하기 위해 sourceforge에서 배포하는 JSON-lib (http://sourceforge.net/projects/json-lib/files/)를 사용합니다.

결과값 result : 200, processcode : 20002 에 따라 대상자를 더 보낼 수도 메시지 전송을 마칠 수도 있습니다.

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

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

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

2) 푸시를 받을 대상자 및 메시지(JSON text 형식), 그 외 설정값들을 셋팅 합니다. 한 번에 보내는 대상자는 500건 이하로 해야 합니다.

$members = ["member1", "member2"];

$users = array(
	http_build_query($key),
	"msgidx=". $msgidx
);

for ($i = 0; $i < count($members) ; ++$i) {
	// array 타입 개별 메시지
	$message = array(
		"message"			=> $members[$i]."_개별 메시지_".$i,	// 개별 메시지 (필수)
		"ck1"				=> "",
		"ck2"				=> "",
		"ck3"				=> "",
		"cv1"				=> "",
		"cv2"				=> "",
		"cv3"				=> "",
		"lcode"				=> "",
		"and_priority"			=> "H",
	);

	$option = array(
		"identity" 			=> $members[$i],		//  identity (필수)
		"message" 			=> json_encode($message), 	// json 타입의 개별메시지 (필수)
		"prv_attachefname" 		=> "",
		"prv_linkurl" 			=> "",
		"prv_title" 			=> ""
	);

	$users[] = http_build_query($option);
}

if( !count($users) ) {
	echo json_encode(array(
		"result"  => "4040", 
		"message" => "전송 대상 정보가 없습니다."
	));
	exit();
}

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

$param = implode($users, "&");

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/setSTSJsonPushs.jsp

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

$url = ' https://api-v2.fingerpush.com/rest/sts/v4/setSTSJsonPushs.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 변수로 변환합니다.

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

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

6) 해당 결과로 받은 내용을 JSON형식으로 받아 파싱한 결과에 따라 다음 프로세스(대상자 발송)를 준비합니다. 결과값 result : 200, processcode : 20002 에 따라 대상자를 더 보낼 수도 메시지 전송을 마칠 수도 있습니다.

메시지 전송 종료 정보 발송

'2. 다수의 대상자 발송 > 메시지 전송 종료 정보 발송’을 참조해 주세요.