MyID2.0 Implementation Guide

# Web

# Overview

MyID Client SDK는 Issuer, Verifier용 어플리케이션이 쯩 앱과 연동하기 위한 SDK입니다. 이 문서는 모바일 웹 어플리케이션과 쯩 앱 연동 관련 문서이며, Android나 iOS는 별도 문서로 제공됩니다.

해당 SDK의 구현은 쯩 앱 내 WebView를 통해서 구동된 웹 앱과 쯩 앱이 연동하는 것을 가정하고 있습니다. 그 외 경우에 대해서는 PARAMETA 담당자(myid_techsupport@parametacorp.com)에게 문의바랍니다

# MyID SDK Client Web Sequence

다음은 쯩 앱에서 모바일 웹 앱과 연동하는 2가지 경우에 대한 전형적인 순서를 나타낸 것입니다.

  • 쯩 앱 내 WebView를 통해 모바일 웹 앱을 구동하고 Credential을 발급받는 시나리오
  • 쯩 앱 내 WebView를 통해 모바일 웹 앱을 구동하고 Presentation을 요청하고 전달받는 시나리오

이 문서에서는 JavaScript를 사용하는 Web 클라이언트용 SDK로써, 아래 sequence diagram에서 파란색 글씨 부분에 해당하는 API에 대해서 설명합니다.

uml diagram

# Implementation Preparation

# SDK 라이브러리

MyID 서비스를 사용하기 위해 사용되는 라이브러리는 MyID SDK Client Web 폴더로 제공이됩니다.
MyID Client SDK - Web 에서 다운로드 가능합니다.

# SDK Import

myid-sdk-client-web 폴더를 원하는 디렉토리에 위치시킨 후, 아래와 같은 방식 중 원하는 방식으로 import합니다. (ES Module Import 방식 지원)

// Module Import
import Zzeung from "./your-directory/myid-sdk-client-web";

or

<!-- build 폴더에 있는 myid-sdk-client-web.min.js 를 HTML 상에서 직접 import -->
<script src="./your-directory/myid-sdk-client-web.min.js"></script>

# Implementation Guide

MyID SDK Client Web에는 Zzeung 이라는 단일 Class가 존재합니다.

# Zzeung

Zzeung 클래스는, 쯩 앱 내 WebView로 구동된 웹 어플리케이션과 쯩 앱 간의 연동을 위한 API들을 제공하고 있습니다.

import Zzeung from "./lib/myid-sdk-client-web";

static request() - deprecated

Note : note : 이 API는 Web SDK 1.1.0에서 부터 deprecated 되었습니다. Web SDK 1.1.0 이상을 사용하실 때는 아래 static sendVcp()을 사용하시기 바랍니다

서버로부터 전달받은 JWT를 Holder의 쯩 앱으로 전송하고, 이에 대한 response를 Promise로 전달 받습니다. Error Code가 0이 아닌 코드는 Catch Block으로 throw합니다.

Parameters

params (Object json): Holder에게 보낼 JWT Object json,
callback ((response) => void, optional): Response object를 인자로 받는 콜백 함수. (ES5 환경에서 동기적 흐름을 제어하기 위한 용도로 사용 가능.)

Returns

retCode === 0 인 경우,
Object {
   retCode (number) : 응답 코드,
   retMessage (string) : 응답 메세지,
   jwt (string) : 쯩 앱으로부터 받은 JWT string
}

retCode !== 0 인 경우,
Object {
   retCode (number) : 응답 코드,
   retMessage (string) : 응답 메시지,
}

Zzeung.request(params: string, callback?: (response) => void) => Promise<object>

Example

import Zzeung from "./lib/myid-sdk-client-web";

try {
   const jwt = { type: "did_init", message: "ea15a...." };
   Zzeung.request(jwt).then((response) => {
      // callback에 원하는 로직 삽입
      console.log(response.jwt);
   });
} catch (e) {
   console.error(e);
}

static sendVcp() - Available from v1.1.0

서버로부터 전달받은 JWT를 Holder의 쯩 앱으로 전송하고, 이에 대한 response를 Promise로 전달 받습니다. 기존의 request()를 대체하여 Error Code를 throw하는 것이 아닌 프로세스상에서 Return합니다.

Parameters

params (Object json): Holder에게 보낼 JWT Object json,
callback ((response) => void, optional): Response object를 인자로 받는 콜백 함수. (ES5 환경에서 동기적 흐름을 제어하기 위한 용도로 사용 가능.)

Returns

retCode === 0 인 경우,
Object {
   retCode (number) : 응답 코드,
   retMessage (string) : 응답 메세지,
   jwt (string) : 쯩 앱으로부터 받은 JWT string
}

retCode !== 0 인 경우,
Object {
   retCode (number) : 응답 코드,
   retMessage (string) : 응답 메시지,
}

Zzeung.sendVcp(params: string, callback?: (response) => void) => Promise<object>

Example

import Zzeung from "./lib/myid-sdk-client-web";

try {
   const jwt = { type: "did_init", message: "ea15a...." };
   Zzeung.sendVcp(jwt).then((response) => {
      // callback에 원하는 로직 삽입
      console.log(response.jwt);
   });
} catch (e) {
   console.error(e);
}

static close()

쯩 앱의 WebView를 닫고, 이전 화면으로 돌아갑니다. msg 인자에 값을 입력하면 WebView가 닫힘과 동시에 쯩 앱 내에서 Toast 알림을 표시할 수 있습니다.

Parameters

msg (string, optional): WebView가 닫힘과 동시에 쯩 앱에서 표시할 Toast 메시지 string

Zzeung.close(msg: string | null) => void

Example

import Zzeung from "./lib/myid-sdk-client-web";
Zzeung.close(“발급이 완료되었습니다.”);

static openWithBrowser()

보여주고자 하는 페이지를 브라우저로 띄웁니다.

Parameters

url (string): 보여주고자 하는 페이지의 URL

Zzeung.openWithBrowser(url: string) => void

Example

import Zzeung from "./lib/myid-sdk-client-web";
Zzeung.openWithBrowser(“https://zzeung.id/”);

static hasValidCredential()

지정한 Issuer가 발급한 VC Type의 유효한 크레덴셜 존재 여부를 알려 줍니다. 여기서 유효한 크레덴셜이란 만료기간 이내의 폐기되지 않은 크레덴셜입니다.

Parameters

params (object): {
  did (string): Issuer DID
  vcType (string): Credential의 type
}

Returns

0 : 해당 조건의 유효한 Credential 없음,
1 : 해당 조건의 유효한 Credential 있음,
2 : 해당 조건의 Credential이 존재하지만, 네트웍 오류 등으로 인해서 폐기 여부를 알 수 없음

Zzeung.hasValidCredential(params: {
  did: string;
  vcType: string;
}) => Promise<number>

Example

import Zzeung from "./lib/myid-sdk-client-web";
const hasValidCredential = await Zzeung.hasValidCredential({
   did: "did:icon:3301:73dba034067d7bd7d2e761e630ed8f0cf7bf53dadcdaba83",
   vcType: "https://vc.zzeung.kr/vocab#FinancialIdCredential",
});