Client(JavaScript) Package Guide

코딩역량인증시험 인증서 취득 서비스의 Client(JavaScript) Package Guide 입니다.

브라우저에서만 사용 가능하며, nodejs 등 기타 환경에서는 사용 불가능합니다.

Install

npm package및 jsdeliver cdn으로 설치 가능합니다.

1. npm (권장)

npm install @grepp/zelos-grade-getter --save
Shell
복사

2. cdn

<script src="https://cdn.jsdelivr.net/npm/@grepp/zelos-grade-getter@version/dist/index.min.js"></script>
HTML
복사

EX) 1.0.0버전을 다운받을 경우

<script src="https://cdn.jsdelivr.net/npm/@grepp/zelos-grade-getter@1.0.0/dist/index.min.js"></script>
HTML
복사

npm과 cdn의 차이점

npm으로 설치했을 경우, type이 제공되며 import 구문을 통해 사용 가능합니다. 따라서, npm 버전 사용을 권장드립니다. 두 버전의 다른 차이는 없습니다.

import { init, request } from '@grepp/zelos-grade-getter'
TypeScript
복사

cdn의 설치는 type이 제공되지 않으며, window 아래 다음 객체를 통해 패키지에 접근 할 수 있습니다.

zelos.gradeGetter

EX)
zelos.gradeGetter.init
zelos.gradeGetter.request
JavaScript
복사

Initialize

패키지를 사용하기 위해 먼저 initialize가 필요합니다.

function init(appId: string): void
TypeScript
복사

init 함수를 호출하고 APP ID를 파라미터로 전달해야 합니다.

APP ID확인 방법은 링크를 확인해주세요.

패키지 내 다른 함수 호출 전에 최초로 호출되어야 하며, 중복 호출할 수 없습니다.

// npm을 통한 설치시
import { init } from '@grepp/zelos-grade-getter'

init(appId);
JavaScript
복사

// cdn을 통한 설치시
zelos.gradeGetter.init(appId);
JavaScript
복사

Initialize 여부 확인

isInitialized 함수를 통해 현재 initialize 여부를 확인할 수 있습니다.

// npm을 통한 설치시
import { isInitialized } from '@grepp/zelos-grade-getter'

isInitialized(); // true면 초기화 완료, false면 초기화 이전
TypeScript
복사

// cdn을 통한 설치시
zelos.gradeGetter.isInitialized(); // true면 초기화 완료, false면 초기화 이전
TypeScript
복사

Request

팝업을 생성하고, 사용자(유저)가 보유한 인증서(자격증)정보를 취득합니다.

함수는 callback을 받는 request 함수, Promise를 리턴하는 asyncRequest 함수 2가지가 있습니다.

function request(callback: GradeGetterCallback, options?: GradeGetterRequestOptions): void

function asyncRequest(options?: GradeGetterRequestOptions): Promise<GradeGetterResponse>
TypeScript
복사

각 함수의 파라미터 규칙은 다음과 같습니다.

request 함수는 첫번째 파라미터로 callback을 반드시 전달해야 합니다.

request 함수의 두번째 파라미터인 options는 필수가 아닙니다.

Promise를 반환하는 asyncRequest는 options 객체만 선택적으로 전달받습니다.

EX) 사용 예시

// npm을 통한 설치시
import { request, asyncRequest } from '@grepp/zelos-grade-getter'

const callback = (certificateData: GradeGetterResponse) => {
};

const handleOnClick = () => {
	request(callback);
};

element.onClick = handleOnClick;

const handleOnAsyncRequestClick = async () => {
	const certificateData = await asyncRequest();
};

element.onClick = () => handleOnAsyncRequestClick();
TypeScript
복사

// cdn을 통한 설치시
const callback = (certificateData) => {
};

const handleOnClick = () => {
	zelos.gradeGetter.request(callback);
};

element.onClick = handleOnClick;

const handleOnAsyncRequestClick = async () => {
	const certificateData = await zelos.gradeGetter.asyncRequest();
};

element.onClick = () => handleOnAsyncRequestClick();
JavaScript
복사

Request시 주의점

해당 패키지는 팝업을 통해 사용자에게 인증서를 선택 및 전달받도록 구성되어 있습니다.

이때, iOS Safari에서는 Element의 onClick 함수를 통해서만 팝업 차단 없이 팝업(신규 탭)이 동작합니다.

따라서 다음 예시와 같이 코드를 작성해 주셔야 iOS 에서의 자연스러운 동작을 보장받을 수 있습니다.

onClick 함수 Scope 내에서 request를 호출

// good case
const handleOnClick = () => {
	request(callback);
};

element.onClick = handleOnClick; // element의 onClick scope 내

// bad case
document.ready = () => {
	request(callback); // element의 onClick이 아님 - 팝업 차단됨
};

setTimeout(() => request(callback), 1000); // element의 onClick이 아님 - 팝업 차단됨

... 기타 다른 스코프에서 호출
TypeScript
복사

async await, Promise 사용 시 가장 첫 번째로 asyncRequest 호출

//good case
const handleOnAsyncRequestClick = async () => {
	await asyncRequest(); // asyncRequest를 가장 먼저 호출
	await otherFunction();
}

element.onClick = () => handleOnAsyncRequestClick();

const handleOnPromiseRequestClick = () => {
	asyncRequest() // asyncRequest를 가장 먼저 호출
	.then(() => otherFunction());
}

element.onClick = handleOnPromiseRequestClick;

// bad case
const handleOnAsyncRequestClick = async () => {
	await otherFunction();
	await asyncRequest(); // asyncRequest를 나중에 호출 - popup 차단됨
}

element.onClick = () => handleOnAsyncRequestClick();

const handleOnPromiseRequestClick = () => {
	otherFunction()
	.then(() => asyncRequest()); // asyncRequest를 나중에 호출 - popup 차단됨
}

element.onClick = handleOnAsyncRequestClick;
TypeScript
복사

Response Data

request를 통해 전달받는 데이터는 다음과 같습니다.

type GradeGetterResponse = {
  isSuccess: boolean,
  data?: Readonly<CertificateGradeData>,
  error?: string,
  errorCode?: ErrorCode,
};
TypeScript
복사

Property	설명
isSuccess	인증서 데이터 취득 성공 여부
data	isSuccess = true 시 전달되는 인증서 데이터
error	isSuccess = false 시 전달되는 에러 메시지
errorCode	isSuccess = false 시 전달되는 에러 코드

isSuccess가 true일 경우에는 인증서 정보 취득에 성공한 것이며, data에 결과값이 전달됩니다.

그 외의 경우에는 error, errorCode로 각각 에러 내용과 에러 코드가 전달됩니다.

데이터 정보 및 에러 정보는 링크를 확인해주세요.

Request Options

request시 전달하는 option 입니다.

export type GradeGetterRequestOptions = {
  filter?: GradeGetterFilterOption[],
};

export type GradeGetterFilterOption = {
  classification?: CodeEnum,
  minLevel?: 1 | 2 | 3 | 4 | 5,
  languages?: LanguageEnum[],
};
TypeScript
복사

•

GradeGetterRequestOptions 

filter

필터 목록. 전달받고자 하는 인증서를 조건에 맞추어 필터링 하고자 할 때 설정합니다. 빈 값 이거나 vaild한 필터 객체가 존재하지 않으면 필터링이 적용되지 않습니다.

•

GradeGetterFilterOption Property

classification	시험 종류. 빈 값이면 모든 시험을 노출.
minLevel	최소 레벨. 빈 값 이거나, 1이면 모든 레벨을 노출. PCCE의 경우는 최대 레벨이 4 이므로, 5를 넣으면 노출되지 않습니다.
languages	코딩 언어 목록. 빈 값 이거나, 빈 array이면 모든 코딩 언어를 노출.

EX1) PCCE 시험에 최소 레벨이 3 이상이며 Java와 JavaScript 언어로 응시한 인증서만 노출

request(callback, {
	filter: [{
		classification: 'PCCE',
		minLevel: 3,
		languages: ['Java', 'JavaScript'],
	}],
});
TypeScript
복사

EX2) 시험 상관 없이 JavaScript 언어로 응시하였거나, PCCP 시험이면서 Python, C++, JavaScript 언어로 응시한 인증서만 노출

request(callback, {
	filter: [{
		languages: ['JavaScript'],
	}, {
		classification: 'PCCP',
		languages: ['Python3', 'C++', 'JavaScript'],
	}],
});
TypeScript
복사

EX3) PCCE C++ 4레벨 이상 이거나, PCCP 2레벨 이상인 인증서만 노출

request(callback, {
	filter: [{
		classification: 'PCCE',
		languages: ['C++'],
		minLevel: 4,
	}, {
		classification: 'PCCP',
		minLevel: 2,
	}],
});
TypeScript
복사

EX4) 잘못된 필터 객체. 필터링이 적용되지 않음

request(callback, {
	filter: [null],
});

request(callback, {
	filter: {
		languages: ['JavaScript'],
	},
});

... 등 컨벤션에 맞지 않는 filter
TypeScript
복사

Stop Request

request를 임의로 취소할 때 사용합니다. 호출 시 팝업이 닫히고 request가 종료되며, callback 및 Promise에 오류가 전달됩니다.

// npm을 통한 설치시
import { request, stop } from '@grepp/zelos-grade-getter'

request((response) => {
// stop시 response 데이터는 다음과 같습니다.
//{
//	isSuccess: false,
//	error: 'Request is canceled manually.',
//	errorCode: 11,
//}
});

stop();
TypeScript
복사

// cdn을 통한 설치시

zelos.gradeGetter.request((response) => {
// stop시 response 데이터는 다음과 같습니다.
//{
//	isSuccess: false,
//	error: 'Request is canceled manually.',
//	errorCode: 11,
//}
});

zelos.gradeGetter.stop();
TypeScript
복사

인증서 데이터 정보

!주의!
JavaScript에서 전달되는 인증서 정보는 사용자(유저)에 의한 변조 가능성이 있으므로, 웹 화면에 정보를 띄우는 용 및 참고 용으로만 사용하세요. 
Token을 Back-end 등 안전한 환경으로 전달한 후, 코딩역량인증시험 서버의 Token api를 호출하여 검증된 데이터를 취득해주세요.

Token api 호출 가이드

// 시험 종류
type CodeEnum = 'PCCP' | 'PCCE';
// 언어 종류
type LanguageEnum = "C++" | "Python3" | "Java" | "JavaScript";

type CertificateGradeData = {
  /**
   * 인증 토큰 - 서버에서 유효한 인증서인지 검증 및 인증서 정보 취득에 사용.
   */
  token: string,
  /**
   * 인증서 일련번호.
   */
  certificate: number,
  /**
   * 인증서 고유번호.
   */
  code: string,
  /**
   * 인증서 레벨.
   */
  level?: number | null,
  /**
   * 시험 언어
   */
  language?: LanguageEnum,
  /**
   * 시험 일시 / 인증서 취득일
   */
  startAt?: string | null,
  user: {
    /**
     * 이름
     */
    name?: string | null,
    /**
     * 생년월일
     */
    birthdate?: string | null,
  },
  /**
   * 시험 구분
   */
  classification: {
    /**
     * PCCP | PCCE
     */
    code: CodeEnum,
    /**
     * 코딩전문역량인증 | 코딩필수역량인증
     */
    summary?: string,
  },
};
TypeScript
복사

token	코딩역량인증시험측 서버로 Token api를 호출하여 검증된 인증서 정보를 취득하는데 사용합니다. 가이드 링크
certificate	인증서 일련번호.
code	인증서 고유번호.
level	취득한 레벨.
language	시험에 응시한 코딩 언어입니다.
startAt	시험 일시입니다. 코딩역량인증시험은 시험일과 취득일이 같으므로, 취득일로 사용할 수 있습니다. YYYY-MM-DD’T’HH:mm:ssZ
user.name	유저(사용자) 명.
user.birthdate	유저(사용자) 생년월일. YYYY-MM-DD
classification.code	시험 종류. PCCP 혹은 PCCE
classification.summary	시험 명.

에러 코드 목록

에러 코드	에러 메시지	에러 내용 상세
0	Unknown error.	알 수 없는 에러가 발생하였습니다. 아래 목록에 있지 않은 에러가 발생 시 전달됩니다.
1	Environment that cannot be executed.	패키지를 실행할 수 없는 환경입니다. 브라우저에서 패키지를 로드 해주세요.
2	Request is already in progress. Popup is still open.	request가 아직 진행중입니다. 팝업이 아직 열려있습니다.
3	Request is not in progress.	request가 진행중이 아닙니다.
4	Package is already initialized.	패키지가 이미 초기화 되어있습니다.
5	Package is not initialized.	패키지가 초기화 되어있지 않습니다.
6	Request initialization failed, check the appId and origin, or the popup may be blocked.	request가 실패하였습니다. APP ID가 올바르지 않거나, vaild한 origin이 아니거나, 팝업이 차단되어있을 수 있습니다. APP ID와 origin 설정은 링크 를 참고해주세요.
7	Request is abnormally terminated. Popup is closed.	request가 실패하였습니다. 팝업이 닫혔습니다.
8	Request is abnormally terminated. Frame is closed.	request가 실패하였습니다. iframe이 제거되었습니다.
9	Init prop appId must be a string.	init 함수에서 appId 프로퍼티가 없거나 string이 아닙니다. 정확한 appId를 넣어주세요.
10	Request prop callback must be a function.	request 함수에서 callback이 없거나 함수가 아닙니다. callback 함수 프로퍼티를 반드시 전달 해 주세요.
11	Request is canceled manually.	stop 함수를 통해 request가 취소되었습니다.