페이지 이동경로
  • 문서>
  • 시작하기>
  • JavaScript

시작하기

JavaScript

이 문서는 Kakao SDK for JavaScript(이하 JavaScript SDK) 사용법을 설명합니다.

설치

JavaScript SDK 파일을 웹 페이지에 포함(Include)시킵니다. script 태그 내부에 버전과 해당 버전의 Integrity 값을 정확히 기입해야 합니다. SDK 다운로드에서 확인 및 복사할 수 있습니다. 아래 예제를 참고합니다.

<script src="https://t1.kakaocdn.net/kakao_js_sdk/${VERSION}/kakao.min.js"
  integrity="${INTEGRITY_VALUE}" crossorigin="anonymous"></script>
참고: JavaScript SDK 데모

[도구]에서 JavaScript SDK의 기능 및 동작을 참고할 수 있는 데모를 제공합니다.

초기화

다운로드를 참고하여 JavaScript SDK를 웹 페이지에 포함한 후, 다음의 JavaScript SDK 초기화 함수를 호출합니다. JAVASCRIPT_KEY에 [내 애플리케이션] > [앱 키]에서 확인한 JavaScript 키를 할당해야 합니다.

Kakao.init('JAVASCRIPT_KEY');
Kakao.isInitialized();

다음은 초기화 함수를 호출하고, 이어서 초기화가 잘 되었는지 확인하는 함수를 호출하는 예제입니다.

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <title>Kakao JavaScript SDK</title>
  <script src="https://t1.kakaocdn.net/kakao_js_sdk/${VERSION}/kakao.min.js"
    integrity="${INTEGRITY_VALUE}" crossorigin="anonymous"></script>
  <script>
    // SDK를 초기화 합니다. 사용할 앱의 JavaScript 키를 설정해야 합니다.
    Kakao.init('JAVASCRIPT_KEY');

    // SDK 초기화 여부를 판단합니다.
    console.log(Kakao.isInitialized());
  </script>
</head>
<body></body>
</html>

JavaScript SDK가 정상적으로 초기화된 상태라면, 해당 웹 페이지 실행 시 개발자 도구 콘솔에 true가 출력됩니다. false가 출력됐다면 초기화에 사용한 JavaScript 키 값이 올바른지 확인합니다.

플랫폼 설정

JavaScript SDK를 통해 카카오 API를 호출하려면 [내 애플리케이션] > [플랫폼] > [Web]에 도메인을 등록해야 합니다. 자세한 안내는 플랫폼 등록을 참고합니다.

지원하는 웹 브라우저

JavaScript SDK는 가장 많이 사용되는 웹 브라우저를 지원합니다. 플랫폼별 지원하는 웹 브라우저와 버전 정보는 다음과 같습니다.

Browser / Platform Android iOS macOS Windows
Chrome* O O O O
Edge* O O O O
Firefox* O O O O
Safari X O O X
Internet Explorer (IE) X X X O**

* Chrome, Edge, Firefox의 경우, 최신 및 직전 버전에 최적화되어 있음

** IE 11만 지원

하이브리드 앱 가이드

하이브리드 애플리케이션(이하 하이브리드 앱) 내 웹 페이지에서 JavaScript SDK를 사용할 경우, 웹뷰(WebView)에서 JavaScript SDK가 올바르게 동작하도록 하려면 아래 동작을 위한 추가 조치가 필요합니다.

카카오톡 실행

JavaScript SDK는 카카오 로그인카카오톡 공유 기능 사용 시, 카카오톡을 실행하는 URL을 만들어 호출합니다. 상용 브라우저에서 해당 기능들이 실행될 때는 브라우저가 URL을 통해 앱을 실행할 수 있어 정상적으로 카카오톡이 실행되지만, 웹뷰에서는 앱을 실행하지 못하고 에러가 발생합니다.

팝업 웹뷰 처리

또한 JavaScript SDK의 카카오 로그인 기능 중 일부는 보다 향상된 사용자 경험(UX)을 위하여 팝업(Pop-up) 윈도우를 사용합니다. JavaScript에서 팝업 윈도우가 필요한 기능이 정상적으로 동작하게 하려면 window.open(), window.close() 호출에 맞춰 팝업에 해당하는 웹뷰가 생성 및 제거되어야 합니다.

개발 가이드: Android

카카오톡 패키지명 설정

Android 11 이상에서 JavaScript SDK을 이용하여 카카오 로그인과 카카오톡 공유를 사용할 경우, 반드시 AndroidManifest.xml에 카카오톡의 패키지명을 명시해야 합니다. 카카오톡 패키지명 미등록 시, Android Framework에서 호출을 차단하여 해당 기능을 사용할 수 없습니다.

<manifest package="com.example.sample">
    <queries>
        <package android:name="com.kakao.talk" />
    </queries>
    ...
</manifest>
카카오톡 실행

Android 앱에서 웹뷰를 통해 앱을 실행하려면 Intent URI를 이용합니다. 이에 대한 자세한 정보는 Android Intents with Chrome을 참고합니다.

JavaScript SDK가 카카오톡 실행을 위한 Intent URI를 생성해 호출합니다. 웹뷰에서는 WebViewClient#shouldOverrideUrlLoading 메서드를 오버라이딩(Override)하여 Intent를 파싱(Parsing)하고, 해당 Activity를 실행해야 합니다.

webView = // 메인 웹뷰

// 공통 설정
webView.settings.run {
    javaScriptEnabled = true
    javaScriptCanOpenWindowsAutomatically = true
    setSupportMultipleWindows(true)
}

webView.webViewClient = object: WebViewClient() {

    override fun shouldOverrideUrlLoading(view: WebView,request: WebResourceRequest): Boolean {
        Log.d(TAG, request.url.toString())

        if (request.url.scheme == "intent") {
            try {
                // Intent 생성
                val intent = Intent.parseUri(request.url.toString(), Intent.URI_INTENT_SCHEME)

                // 실행 가능한 앱이 있으면 앱 실행
                if (intent.resolveActivity(packageManager) != null) {
                    startActivity(intent)
                    Log.d(TAG, "ACTIVITY: ${intent.`package`}")
                    return true
                }

                // Fallback URL이 있으면 현재 웹뷰에 로딩
                val fallbackUrl = intent.getStringExtra("browser_fallback_url")
                if (fallbackUrl != null) {
                    view.loadUrl(fallbackUrl)
                    Log.d(TAG, "FALLBACK: $fallbackUrl")
                    return true
                }

                Log.e(TAG, "Could not parse anythings")

            } catch (e: URISyntaxException) {
                Log.e(TAG, "Invalid intent request", e)
            }
        }

        // 나머지 서비스 로직 구현

        return false
    }
}
팝업 웹뷰 처리

Android 앱에서 웹뷰에 WebChromeClient를 설정하면, 아래 메서드가 호출됩니다.

해당 메서드를 오버라이딩하여 팝업 윈도우의 웹뷰를 생성 및 제거할 수 있습니다.

webView = // 메인 웹뷰
webViewLayout = // 웹뷰가 속한 레이아웃

// 공통 설정
webView.settings.run {
    javaScriptEnabled = true
    javaScriptCanOpenWindowsAutomatically = true
    setSupportMultipleWindows(true)
}

webView.webChromeClient = object: WebChromeClient() {

    /// ---------- 팝업 열기 ----------
    /// - 카카오 JavaScript SDK의 로그인 기능은 popup을 이용합니다.
    /// - window.open() 호출 시 별도 팝업 webview가 생성되어야 합니다.
    ///
    override fun onCreateWindow(
        view: WebView,
        isDialog: Boolean,
        isUserGesture: Boolean,
        resultMsg: Message
    ): Boolean {

        // 웹뷰 만들기
        var childWebView = WebView(view.context)

        // 부모 웹뷰와 동일하게 웹뷰 설정
        childWebView.run {
            settings.run {
                javaScriptEnabled = true
                javaScriptCanOpenWindowsAutomatically = true
                setSupportMultipleWindows(true)
            }
            layoutParams = view.layoutParams
            webViewClient = view.webViewClient
            webChromeClient = view.webChromeClient
        }

        // 화면에 추가하기
        webViewLayout.addView(childWebView)
        // TODO: 화면 추가 이외에 onBackPressed() 와 같이
        //       사용자의 내비게이션 액션 처리를 위해
        //       별도 웹뷰 관리를 권장함
        //   ex) childWebViewList.add(childWebView)

        // 웹뷰 간 연동
        val transport = resultMsg.obj as WebView.WebViewTransport
        transport.webView = childWebView
        resultMsg.sendToTarget()

        return true
    }

    /// ---------- 팝업 닫기 ----------
    /// - window.close()가 호출되면 앞에서 생성한 팝업 webview를 닫아야 합니다.
    ///
    override fun onCloseWindow(window: WebView) {
        super.onCloseWindow(window)

        // 화면에서 제거하기
        webViewLayout.removeView(window)
        // TODO: 화면 제거 이외에 onBackPressed() 와 같이
        //       사용자의 내비게이션 액션 처리를 위해
        //       별도 웹뷰 array 관리를 권장함
        //   ex) childWebViewList.remove(childWebView)
    }
}

개발 가이드: iOS

카카오톡 실행

iOS 앱의 경우, 유니버설 링크가 호출되었을 때는 별도 처리 없이 앱 실행이 가능하지만, 커스텀 URL 스킴이 호출된 경우 해당 URL을 웹뷰에서 open(_ url:) 메서드를 호출하여 앱을 실행해야 합니다.

func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void ) { 
    print(navigationAction.request.url?.absoluteString ?? "") 

    // 카카오 SDK가 호출하는 커스텀 URL 스킴인 경우 open(_ url:) 메서드를 호출합니다. 
    if let url = navigationAction.request.url , ["kakaolink"].contains(url.scheme) {

        // 카카오톡 실행 가능 여부 확인 후 실행
        if UIApplication.shared.canOpenURL(url) {
            UIApplication.shared.open(url, options: [:], completionHandler: nil)
        }

        decisionHandler(.cancel) return 
    } 

    // 서비스에 필요한 나머지 로직을 구현합니다. 
    decisionHandler(.allow) 
}
팝업 웹뷰 처리

웹뷰에 WKUIDelegate를 설정하면 JavaScript에서 팝업 기능이 실행될 때 아래 메서드가 호출됩니다.

아래 예제를 참고하여 팝업 윈도우에 필요한 웹뷰를 생성 및 제거하는 로직을 구현합니다.

class ViewController: UIViewController, WKUIDelegate, WKNavigationDelegate {

    // 웹뷰 목록 관리
    var webViews = [WKWebView]()

    ...

    /// ---------- 팝업 열기 ----------
    /// - 카카오 JavaScript SDK의 로그인 기능은 popup을 이용합니다.
    /// - window.open() 호출 시 별도 팝업 webview가 생성되어야 합니다.
    ///
    func webView(_ webView: WKWebView,
                 createWebViewWith configuration: WKWebViewConfiguration,
                 for navigationAction: WKNavigationAction,
                 windowFeatures: WKWindowFeatures
    ) -> WKWebView? {
        guard let frame = self.webViews.last?.frame else {
            return nil
        }

        // 웹뷰를 생성하여 리턴하면 현재 웹뷰와 parent 관계가 형성됩니다.
        return createWebView(frame: frame, configuration: configuration)
    }

    /// ---------- 팝업 닫기 ----------
    /// - window.close()가 호출되면 앞에서 생성한 팝업 webview를 닫아야 합니다.
    ///
    func webViewDidClose(_ webView: WKWebView) {
        destroyCurrentWebView()
    }

    // 웹뷰 생성 메서드 예제
    func createWebView(frame: CGRect, configuration: WKWebViewConfiguration) -> WKWebView {
        let webView = WKWebView(frame: frame, configuration: configuration)
        
        // set delegate
        webView.uiDelegate = self
        webView.navigationDelegate = self
                
        // 화면에 추가
        self.view.addSubview(webView)

        // 웹뷰 목록에 추가
        self.webViews.append(webView)

        // 그 외 서비스 환경에 최적화된 뷰 설정하기

        
        return webView
    }

    // 웹뷰 삭제 메서드 예제
    func destroyCurrentWebView() {
        // 웹뷰 목록과 화면에서 제거하기
        self.webViews.popLast()?.removeFromSuperview()
    }

}

v1에서 v2로 업그레이드

다음은 JavaScript SDK v1(2.0.0 미만 버전)에서 JavaScript SDK v2로 업그레이드하는 사용자를 위한 참고 정보입니다.

주요 변경 사항

Internet Explorer 최소 지원 버전 변경

지원하는 웹 브라우저 중 Internet Explorer(이하 IE)의 최소 지원 버전이 11로 변경되었습니다. IE 9, 10 버전에 대한 지원이 필요한 경우, Legacy JavaScript SDK를 사용해야 합니다.

JavaScript SDK 적용 방법 변경

JavaScript SDK v2는 script 태그 내부의 SDK 파일 경로에 버전을 명시해야 합니다.

integrity는 해시(Hash)값이 일치하는 스크립트(Script) 파일만 브라우저에서 실행을 허용하는 Subresource Integrity (SRI)를 위한 속성으로, 보안 강화를 위해 사용을 권장합니다. JavaScript SDK 버전별 integrity 값은 변경 이력에서 확인 및 복사할 수 있습니다. 아래 예제와 다운로드를 참고합니다.

<!-- Before -->
<script src="https://t1.kakaocdn.net/kakao_js_sdk/v1/kakao.min.js"></script>

<!-- After -->
<script src="https://t1.kakaocdn.net/kakao_js_sdk/${VERSION}/kakao.min.js"
  integrity="${INTEGRITY_VALUE}" crossorigin="anonymous"></script>

Promise 패턴 도입

JavaScript SDK v2의 함수는 Promise 객체를 반환합니다. Legacy JavaScript SDK에서 지원하던 success, fail, always 콜백 파라미터는 Promise.then(), Promise.catch() 메서드로 변경해야 합니다. 아래 예시와 기능별 문서의 내용을 참고합니다.

// Before
Kakao.API.request({
  url: '/v2/user/me',
  success: function(response) {
    console.log(response);
  },
  fail: function(error) {
    console.log(error);
  },
});

// After
Kakao.API.request({
  url: '/v2/user/me',
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

팝업 방식으로 로그인 지원 종료

JavaScript SDK v2는 보안 권고사항에 따라, 클라이언트에서 엑세스 토큰을 발급받는 '팝업 방식으로 로그인' 관련 함수를 지원하지 않습니다. 대신 Kakao.Auth.authorize() 함수를 사용해야 합니다. 해당 함수에 대한 자세한 내용은 카카오 로그인을 참고합니다.

기능 JavaScript SDK v1 JavaScript SDK v2
카카오 로그인 Kakao.Auth.login()
Kakao.Auth.createLoginButton()
Kakao.Auth.loginForm()
Kakao.Auth.autoLogin()
Kakao.Auth.authorize()

모듈명 및 API 요청 URL 변경

서비스 이름 변경과 관련된 일부 모듈명과 API 요청 URL이 변경되었습니다. 아래 표와 기능별 문서를 참고합니다.

기능 JavaScript SDK v1 JavaScript SDK v2
카카오톡 공유 Kakao.Link Kakao.Share
카카오톡 채널 Kakao.PlusFriend Kakao.Channel
카카오톡 채널 관계 확인하기 /v1/api/talk/plusfriends /v1/api/talk/channels

Legacy

Legacy Kakao SDK for JavaScript(이하 Legacy JavaScript SDK) 사용 방법은 다음 링크를 통해 확인할 수 있습니다. 추후 Legacy JavaScript SDK에 대한 지원이 중단될 수 있으므로, 가급적 빠른 시일 내에 최신 버전 JavaScript SDK로 변경할 것을 권장합니다.

더보기