# KCP 휴대폰 본인인증 연동 (iOS/AOS)
휴대폰 본인인증 모듈은 iOS/AOS 어플리케이션 내 webview를 이용하여 연동합니다.
* [iOS 매뉴얼](#ios)
* [AOS 매뉴얼](#aos)
{% hint style="info" %}
휴대폰 본인인증 모듈에 대한 가이드는 [휴대폰 본인인증](https://workspace-help.nhn-commerce.com/aurora-guide/api-1/sms-authentication) 문서를 참고하시길 바랍니다.
{% endhint %}
***
### iOS 매뉴얼
#### 🅐 Xcode 설정 (iOS PASS 앱 관련 스키마 등록)
통신사의 PASS 앱(간편본인확인 앱)이 업데이트됨에 따라 iOS에서 가맹점 앱 서비스를 제공하는 경우, iOS9부터 보안을 강화하는 목적으로 앱을 호출할 때 앱 스키마를 등록해주어야 합니다.
| 통신사 | 앱 스키마 |
| --- | ------------------ |
| SKT | tauthlink |
| KT | ktauthexternalcall |
| LG | upluscorporation |
\
\&#xNAN;**ⓐ Info.plist 파일에 LSApplicationQueriesSchemes 배열을 정의하여 앱 스키마를 등록합니다.**
* ㉠ Information Property List에 LSApplicationQueriesSchemes를 Array 타입으로 추가합니다.
* ㉡ LSApplicationQueriesSchemes 하위 리스트에 String 타입으로 Item을 추가합니다.
* ㉢ `Item` 마다 앱 스키마를 입력합니다.
**ⓑ KCP 휴대폰 본인인증 완료 후 key값을 넘겨받기 위해 스키마를 등록합니다.**
#### 🅑 HTML form 획득
KCP 휴대폰 본인인증 모듈 팝업을 출력하기 위해서 GET /kcp/id-verification을 통해 KCP로 제출할 HTML form을 요청해야 합니다.
> [GET /kcp/id-verification/form](https://docs.shopby.co.kr/?url.primaryName=auth/#/KCPCertification/get-kcp-id-verification-form)
>
> ▶ KCP 본인인증 요청하기\
> 본인 인증을 위한 form을 생성합니다.
{% hint style="info" %}
위 API가 아닌 임의로 form을 작성할 경우, NHN커머스 샵바이 측으로 callback을 받을 수 없습니다.
반드시 위 API 응답값으로 받은 form을 사용하시길 바랍니다.
{% endhint %}
* 응답값은 text/html 형식의 html form 양식입니다.
* returnURI는 scheme:// 형식으로 작성합니다. (예 shopbyexample://form 🅐 - ⓑ 이미지 참고)
* 해당 API 호출시 request header내 platform 정보에 반드시 iOS를 입력하셔야 PASS 앱을 위한 아래의 추가변수가 form양식에 넘어옵니다.
**✓ 예시코드**
```
```
#### 🅒 구현하기
**ⓐ WKWebview 구성**
KCP 휴대폰본인인증 모듈은 웹으로 지원되기 때문에 WKWebview로 구성해야 합니다.
{% code overflow="wrap" %}
```
wkWebView.navigationDelegate = self
wkWebView.uiDelegate = self
wkWebView.configuration.preferences.javaScriptCanOpenWindowsAutomatically = true
```
{% endcode %}
**ⓑ webview - LoadData**
GET /kcp/id-verification호출로 전달받은 form을 webview에 로드합니다.
{% code overflow="wrap" %}
```
var htmlString = """
KCPCert
\(formData) // formData 는 html form 양식입니다.
"""wkWebView.loadHTMLString(htmlString, baseURL: Bundle.main.bundleURL)
```
{% endcode %}
**ⓒ form.submit()**
webview의 evaluateJavaScript을 이용하여 form을 submit합니다.\
form이 submit되면 webview에서 새 창으로 KCP 휴대폰 본인인증 페이지가 노출됩니다.
{% hint style="info" %}
휴대폰 본인인증 화면은 WKWebview에서 새 창으로 열릴 수 있도록 구성해 주셔야 합니다. (ⓒ참고)
`evaluateJavaScript`는 html 폼 양식이 완전히 로드된 후( `webview didFinish`시점) 호출해 주시면 됩니다.
{% endhint %}
{% code overflow="wrap" %}
```
let injectJavaScript: String = """
// form id : form_auth
document.getElementById("form_auth").submit();
"""
var jsStr = injectJavaScript.trimmingCharacters(in: .whitespaces)
jsStr = jsStr.trimmingCharacters(in: .whitespacesAndNewlines)
jsStr = jsStr.trimmingCharacters(in: .newlines)
wkWebView.evaluateJavaScript(jsStr, completionHandler: nil)
```
{% endcode %}
**ⓓ WKWebview 구현**
WKWebview를 새 창으로 구현합니다.
아래 구현방식은 KCP 휴대폰 본인인증 연동을 위한 샘플이며, 개발 시 참고용으로 사용하시길 바랍니다.
{% code overflow="wrap" %}
```
func webView(_ webView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration, for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
let createWebView = WKWebView(frame: self.wkWebView.frame, configuration: configuration)
createWebView.navigationDelegate = self
createWebView.uiDelegate = self
self.view.addSubview(createWebView)
return createWebView
}
```
{% endcode %}
**ⓔ Key 파라미터 획득**
returnURI로 전달받은 URI를 parsing하여 key값을 추출합니다.\
WKWebview Delegate (WKNavigationDelegate)
{% code overflow="wrap" %}
```
public func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, preferences: WKWebpagePreferences, decisionHandler: @escaping (WKNavigationActionPolicy, WKWebpagePreferences) -> Void) {
var policy = WKNavigationActionPolicy.allow
if let requestURL = navigationAction.request.url {
if requestURL.scheme == "shopbyexample" {
if let host = requestURL.host, host == "form" {
if let _ = requestURL.query as String? {
if let urlComponent = URLComponents(url: requestURL, resolvingAgainstBaseURL: true) {
let queryItems = urlComponent.queryItems
if let key = queryItems?.first(where: { $0.name == "key" })?.value {
print("key : \(key)")
}
}
}
policy = .allow
decisionHandler(policy, preferences)
return
}
}
UIApplication.shared.open(requestURL, options: [:], completionHandler: nil)
policy = .cancel
}
decisionHandler(policy, preferences)
}
```
{% endcode %}
#### 🅓 본인인증 결과 조회
해당 key로 본인인증 인증 성공 및 실패 여부를 판단한 뒤, 화면에 성공 및 실패 결과를 전달합니다.
> [GET /kcp/id-verification/response](https://docs.shopby.co.kr/?url.primaryName=auth/#/KCPCertification/get-kcp-id-verification-response)
>
> ▶ KCP 본인인증 결과 조회하기\
> NHN KCP 본인인증 결과를 확인합니다.
#### 🅔 샘플코드(참고)
[KCPCertViewController.swift](https://nhnent.dooray.com/share/tree/WoOk8q6KT1K3MZcLSuyZsw/pages/3615381963904646601/files/3615931128094936280) 참고
***
### AOS 매뉴얼
#### 🅐 webview 세팅
KCP 본인인증을 모바일로 사용하기 위해 webview를 세팅합니다.
{% code overflow="wrap" %}
```
binding.webView.apply {
settings.apply {
javaScriptEnabled = true
javaScriptCanOpenWindowsAutomatically = true
supportMultipleWindows()
}
}
```
{% endcode %}
#### 🅑 HTML form 획득
KCP 휴대폰 본인인증 모듈 팝업을 출력하기 위해서 GET /kcp/id-verification을 통해 KCP로 제출할 HTML form을 요청해야 합니다.
> [GET /kcp/id-verification/form](https://docs.shopby.co.kr/?url.primaryName=auth/#/KCPCertification/get-kcp-id-verification-form)
>
> ▶ KCP 본인인증 요청하기\
> 본인 인증을 위한 form을 생성합니다.
{% hint style="info" %}
위 API가 아닌 임의로 form을 작성할 경우, NHN커머스 샵바이 측으로 callback을 받을 수 없습니다.
반드시 위 API 응답값으로 받은 form을 사용하시길 바랍니다.
{% endhint %}
* 응답값은 text/html 형식의 html form 양식입니다.
* returnURI는 scheme:// 형식으로 작성합니다. (예 shopbyexample://form.html)
**ⓐ webview - LoadData**
GET /kcp/id-verification을 호출하여 전달받은 form을 webview에 로드합니다.
{% code overflow="wrap" %}
```
loadDataWithBaseURL(baseUrl, apiResponseData, "text/html", "UTF-8", "")
```
{% endcode %}
**ⓑ form.submit()**
webview의 evaluateJavaScript을 이용하여 form을 submit합니다.\
form이 submit되면 webview에서 KCP 휴대폰 본인인증 페이지로 리다이렉트 됩니다.
{% code overflow="wrap" %}
```
binding.webView.evaluateJavascript("document.form_auth.submit()") {}
```
{% endcode %}
evaluateJavaScript는 html 폼 양식이 완전히 로드된 후 WebViewClient를 이용하여 호출할 수 있습니다.
{% code overflow="wrap" %}
```
binding.webView.apply {
webViewClient = object : WebViewClient() {
override fun onPageFinished(view: WebView?, url: String?) {
super.onPageFinished(view, url)
if (url?.startsWith(baseUrl) == true) {
binding.webView.evaluateJavascript("document.form_auth.submit()") {}
}
}
}
}
```
{% endcode %}
**ⓒ Key 파라미터 획득**
본인인증이 정상적으로 끝났다면, returnURI로 key값을 전달 받습니다.
```
{YOUR_RETURN_URL}?key=XXXXXXXXXX
```
WebViewClient의 shouldOverrideUrlLoading을 통해 key값을 추출할 수 있습니다.
{% code overflow="wrap" %}
```
binding.webView.apply {
webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(
view: WebView?,
request: WebResourceRequest?
): Boolean {
if (request?.url.toString().startsWith(returnUrl)) {
val uri = Uri.parse(request?.url.toString())
val isContainsKey = uri.queryParameterNames.contains("key") // 파라미터에 key가 포함되어있는지 확인
if (isContainsKey) println("key = ${uri.getQueryParameter("key")}") // key 추출
//TODO: key 추출 이후 과정을 이 곳에서 진행하시면 됩니다.
return isContainsKey
}
return super.shouldOverrideUrlLoading(view, request)
}
}
}
```
{% endcode %}
#### 🅓 본인인증 결과 조회
해당 key로 본인인증 인증 성공 및 실패 여부를 판단한 뒤, 화면에 성공 및 실패 결과를 전달합니다.
> [GET /kcp/id-verification/response](https://docs.shopby.co.kr/?url.primaryName=auth/#/KCPCertification/get-kcp-id-verification-response)
>
> ▶ KCP 본인인증 결과 조회하기\
> NHN KCP 본인인증 결과를 확인합니다.
#### 🅔 샘플코드(참고)
[MainActivity.kt](https://nhnent.dooray.com/share/tree/WoOk8q6KT1K3MZcLSuyZsw/pages/3615381963904646601/files/3615929480452935780) 참고
