$sMallID = '{mall_id}';
$sClientID = '{client_id}';
$sAuthCodeReceiveUrl = '{redirect_uri}'; // 개발자 센터 Redirect URL(s)에 등록된, 응답받을 인증코드를 처리할 url
$sScope = 'mall.read_category,mall.read_product,mall.write_product'; // 예시) 상품분류 (읽기권한), 상품 (읽기+쓰기권한)
$aState = array(
'mall_id' => $sMallID, // 고정
'{임의값a}' => '{임의값b}' // 코드발급 이후 처리에 필요한 값 필요시 추가
);
// 이하 공통
$sAuthCodeRequestUrl = sprintf("https://%s.cafe24api.com/api/v2/oauth/authorize?", $sMallID);
$aRequestData = array(
'response_type' => 'code',
'client_id' => $sClientID,
'state' => base64_encode(json_encode($aState)),
'redirect_uri' => $sAuthCodeReceiveUrl,
'scope' => $sScope,
);
$sUrl = $sAuthCodeRequestUrl . http_build_query($aRequestData);
header('Location: ' . $sUrl);
Plain Text
복사
어드민 API 호출 샘플 코드
•
상기 기본 흐름에 대한 상세 과정과 관련된 샘플 코드를 안내합니다.
1) 쇼핑몰 운영자가 앱 최초 실행
•
쇼핑몰 운영자가 앱을 실행하는 경우 개발자센터에서 앱 생성시 입력한 App URL경로로 앱을 최초 실행합니다.
샘플코드열기
•
앱을 실행한 쇼핑몰 운영자 정보가 아래 형식으로 전달됩니다.
https://{{AppUrl}}/?is_multi_shop={{멀티쇼핑몰여부}}&lang={{쇼핑몰언어}}&mall_id={{mall_id}} &shop_no={{shop_no}}& timestamp= {{timestamp}}& user_id={{로그인아이디}}&user_name={{로그인사용자이름}} &user_type={{사용자유형}}&hmac={{검증용 key}}
2) 쇼핑몰운영자에게 API 호출에 대한 권한동의 승인 요청
$sMallID, $sMallID, $sAuthCodeReceiveUrl, $sScope에 대한 샘플코드는 아래 순서대로 확인하시기 바랍니다.
개발중인 소스코드php열기
$sMallID = '{mall_id}';
$sClientID = '{client_id}';
$sAuthCodeReceiveUrl = '{redirect_uri}'; // 개발자 센터 Redirect URL(s)에 등록된, 응답받을 인증코드를 처리할 url
$sScope = 'mall.read_category,mall.read_product,mall.write_product'; // 예시) 상품분류 (읽기권한), 상품 (읽기+쓰기권한)
$aState = array(
'mall_id' => $sMallID, // 고정
'{임의값a}' => '{임의값b}' // 코드발급 이후 처리에 필요한 값 필요시 추가
);
// 이하 공통
$sAuthCodeRequestUrl = sprintf("https://%s.cafe24api.com/api/v2/oauth/authorize?", $sMallID);
$aRequestData = array(
'response_type' => 'code',
'client_id' => $sClientID,
'state' => base64_encode(json_encode($aState)),
'redirect_uri' => $sAuthCodeReceiveUrl,
'scope' => $sScope,
);
$sUrl = $sAuthCodeRequestUrl . http_build_query($aRequestData);
header('Location: ' . $sUrl);
$sMallID : 쇼핑몰 아이디
•
API 권한을 요청할 쇼핑몰의 아이디를 입력합니다. 앱이 실핼 될때 쇼핑몰 아이디($sMallID)가 파라미터로 전달됩니다.
$sMallID = '{mall_id}';
$sClientID : 클라이언트 아이디(App Key)
•
개발자센터에서 발급받은 App Key를 입력합니다.
$sClientID = '{client_id}';
$sAuthCodeReceiveUrl : 개발자센터 Redirect URL(s)에 등록된 URL
•
개발자센터에서 입력한 응답받을 인증 코드를 처리할 URL인 Redirect URL(s)을 입력합니다. Redirect Url(s)을 여러개 입력하고 싶은 경우 콤마(,)로 입력할 수 있습니다.
$sAuthCodeReceiveUrl = '{redirect_uri}'; // 개발자 센터 Redirect URL(s)에 등록된, 응답받을 인증코드를 처리할 url
$sScope : 쇼핑몰 API 권한(Scope) 정보
•
API를 이용하여 정보를 취득한 쇼핑몰 데이터의 권한을 입력해야 합니다. (상세 내용은 Scope별 사용 동의 참고)
$sScope = 'mall.read_category,mall.read_product,mall.write_product'; // 예시) 상품분류 (읽기권한), 상품 (읽기+쓰기권한)
API의 사용권한이 추가/변경/삭제 되는 경우 반드시 쇼핑몰에 변경된 권한에 대한 동의 후 Access_Token을 재발급 받아야 정상적인 API 호출이 가능합니다.
3) 호출할 수 있는 자격을 증명하기 위한 엑세스 토큰 발급 요청
•
앱에서 API를 호출하기 위한 Access_Token 발급 단계입니다.
$sClientId = '{client_id}';
$sClientSecret = '{client_secret}';
$sThisUrl = '{redirect_uri}'; // https:// 사용
$sCode = $_REQUEST['code'];//2번 응답의 'code'
$sStatus = $_REQUEST['state'];//2번 응답의 'state'
// 이하 공통
$aStatue = json_decode(base64_decode($sStatus), true);
$aFields = array(
'grant_type' => 'authorization_code',
'code' => $sCode,
'redirect_uri' => $sThisUrl
);
$oCurl = curl_init();
curl_setopt_array($oCurl, array(
CURLOPT_URL => 'https://' . $aStatue['mall_id'] . '.cafe24api.com/api/v2/oauth/token',
CURLOPT_POSTFIELDS => http_build_query($aFields),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Authorization: Basic ' . base64_encode($sClientId . ':' . $sClientSecret)
)
));
$sResponse = curl_exec($oCurl);
// 정상 토큰발급 응답인지 확인용 출력해보기
print_r($sResponse);
exit;
4) 인증된 API 호출
•
앱에서 발급받은 Access_Token을 이용하여 API를 호출하는 단계입니다.
$sAcctoken = '{access_token}'; //3번에서 발급 받은 access_token 값
$sEndPointUrl = 'https://{mall_id}.cafe24api.com/api/v2/admin/products';
$sVersion = '2023-09-01'; // 적용할 버전
// 이하 공통
$oCurl = curl_init();
curl_setopt_array($oCurl, array(
CURLOPT_URL => $sEndPointUrl,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer ' . $sAcctoken,
'X-Cafe24-Api-Version: ' . $sVersion
)
));
$sResponse = curl_exec($oCurl);
// API 호출이 정상인지 출력해보기
print_r($sResponse);
exit;
JavaScript작성 규칙
앱의 오류를 방지하기 위하여 반드시 지켜야 하는 자바스크립트 작성 규칙을 안내합니다.
목차
작성 규칙 기본
•
스크립트간의 상호 충돌로 인한 불가피한 오류를 방지하기 위해서 다음 2가지 중 해당하는 규칙에 따라 앱을 개발하시기 바랍니다.
1) 프론트에서 카페24 프론트 API를 사용하는 경우
(function(){
//동작 코드
}(CAFE24API.init('{client_id}')));
2) 프론트에서 API 호출 없이 앱 동작을 위한 수준의 스크립트를 사용하는 경우
//1. 자기 호출 함수 사용
(function(){
//동작 코드
}());
//2. addEventListener 사용
window.addEventListener("load",function(event) {
//동작 코드
},false);
네임스페이스 사용
•
쇼핑몰은 여러개의 앱을 설치하여 사용할 수 있습니다. 때문에 여러 스크립트가 한 페이지(쇼핑몰) 내에 함께 설치되는 경우가 반드시 존재합니다.
•
이 경우, 앱 스크립트간의 상호 충돌로 인한 불가피한 오류가 발생할 수 있습니다.
•
이를 미연에 방지하기 위하여 각 개발사는 아래의 네임스페이스 규칙에 따라 앱을 개발하셔야 합니다.
Caution!
네임스페이스(Namespace)는 각 앱의 전역 자원(변수, 함수 등)이 겹치지 않도록 구분하는 영역을 의미합니다.
즉, 대표로 사용할 하나의 네임스페이스를 선언한 후, 그 안에 전역 자원을 넣어서 사용함으로써 네이밍 간의 충돌을 막는 방법입니다.
네임스페이스 형식
•
다음과 같은 형식을 지켜 네이밍해주세요.
형식 | 설명 | 상세설명 |
{앱 이름}_FRONT_{세부경로}_{파일명} | 파일경로가 /front/product/detail.js 일 때 | SAMPLEAPP_FRONT_PRODUCT_DETAIL |
네임스페이스 패턴 예시
•
프로그램이 복잡해지면 네임스페이스 또는 내부 프로퍼티의 네이밍이 중복될 가능성이 증가합니다.따라서 1번처럼 객체를 바로 선언하는 대신, 2, 3번과 같이 해당 객체가 기존에 존재하는지 여부를 먼저 확인해야 합니다.
1) 위험한 패턴
var SAMPLEAPP_FRONT_PRODUCT_DETAIL = {};
2) 해당 객체의 존재 여부 확인
if (typeof SAMPLEAPP_FRONT_PRODUCT_DETAIL === "undefined") {
var SAMPLEAPP_FRONT_PRODUCT_DETAIL = {};
}
3) 2번과 동일하게 동작하는 Short-hand Code
var SAMPLEAPP_FRONT_PRODUCT_DETAIL = SAMPLEAPP_FRONT_PRODUCT_DETAIL || {};
•
그러나 이런 식으로 객체를 선언할 때마다 검증을 반복하게 되면, 상당량의 중복 코드가 발생하게 됩니다.따라서 아래와 같이 이 작업을 수행해 줄 재사용 함수를 생성하는 것이 효과적입니다.
var SAMPLEAPP_FRONT_PRODUCT_DETAIL = SAMPLEAPP_FRONT_PRODUCT_DETAIL || {};
SAMPLEAPP_FRONT_PRODUCT_DETAIL.makenamespace = function (ns_string) {
var parts = ns_string.split('.'),
parent = SAMPLEAPP_FRONT_PRODUCT_DETAIL,
i;
// 처음에 중복되는 전역 객체명은 제거
if (parts[0] === "SAMPLEAPP_FRONT_PRODUCT_DETAIL") {
parts = parts.slice(1);
}
for (i = 0; i < parts.length; i += 1) {
// 프로퍼티가 존재하지 않는 경우 생성
if (typeof parent[parts[i]] === "undefined") {
parent[parts[i]] = {};
}
parent = parent[parts[i]];
}
return parent;
}
// 네임스페이스 생성 함수
SAMPLEAPP_FRONT_PRODUCT_DETAIL.makenamespace('SAMPLEAPP_FRONT_PRODUCT_DETAIL.modules.module2');
//위 함수는 다음과 같은 결과를 반환합니다.
{
modules: {
module2: {}
}
};
window.onload 사용 금지
•
onload 함수는 동일한 페이지 내에 onload가 이미 존재하는 경우 이후에 중복되는 onload가 동작하지 않는 특성이 있습니다.
•
따라서 window.onload 함수를 사용하게 되면 앱이 외부의 영향을 받아 오류를 일으킬 가능성이 높아지게 됩니다.
Caution!
아래 제시한 방법 이외에도 불가능한 케이스가 존재할 수 있으니, window.onload 사용을 가급적 자제해 주시고,
위에 안내해드린 작성 규칙 기본을 사용해 주시기 바랍니다.
// window.onload 사용
window.onload = function(event) {
//동작 코드
}
CSS 작성 규칙
앱의 CSS Cascading 및 Overriding으로 인하여 화면 깨짐을 방지하기 위하여 반드시 지켜야 하는 CSS 작성 규칙을 안내합니다.
목차
기본 개념
스타일 합치기 (Cascading)
•
ㆍ캐스케이딩이란 4가지 스타일 시트가 태그에 동시에 적용될 때 스타일이 합쳐져서 적용되는 것을 말합니다.
•
ㆍ하나의 태그에 여러 스타일 시트들이 중첩되면 동일한 프로퍼티에 서로 다른 값을 설정하는 충돌이 발생하기도 합니다.
오버라이딩(Overriding)
•
ㆍ오버라이딩은 덮어쓰기로, 동일한 CSS 프로퍼티에 서로 다른 값을 설정하는 충돌 시 우선순위가 높은 스타일을 적용하는 규칙을 말합니다.
•
ㆍ스타일을 무시하는 선택자는 디버깅을 더욱 어렵게 만듭니다. 가능하면 사용하지 않아야 합니다.
스타일 시트 종류
•
ㆍ각 태그에는 다음 4가지 종류의 스타일 시트가 동시에 적용될 수 있습니다.
•
ㆍ우선순위는 다음과 같습니다.
•
1) style 속성에 작성된 스타일
•
2) style 태그에 작성된 스타일
•
3) css 스타일 시트 파일에 작성된 스타일
•
4) 브라우저의 디폴트 스타일
작성 명명 규칙
•
1. 앱에서 사용하고 있다는걸 직관적으로 인식하기 위해 처음에는 app이라는 네임을 사용합니다.
•
2. 구분자는 -(하이픈)으로 구분합니다.
•
3. 요소 class 명칭은 영문 대문자, 숫자, 특수문자로 사용하지 않습니다.
최상위 DOM 객체 사용 예시
구분 | 내용 |
형식 | app-[개발사 이름]-[앱 이름] |
설명 | DOM 최상위 객체에 id 추가후 CSS 코드에 사용 |
예시 |
UI 사이에 직접적 요소를 추가 예시
구분 | 내용 |
형식 | app-[개발사 이름]-[앱 이름]-[요소 이름] |
설명 | UI 사이에 직접적으로 요소를 추가할때 사용 |
예시 |
화면 코드 확인
쇼핑몰의 각 페이지는 페이지에서 수행하고 있는 역할에 따라 코드가 부여되어있습니다. 이것을 화면 코드라고 합니다.
앱 스크립트가 설치될 화면을 지정하려면 해당 화면의 코드를 확인해야 합니다.
Note!
예) '상품 상세 페이지' 안에 앱을 위치시키려고 하는 경우 상품 상세 페이지의 화면코드인 'PRODUCT_DETAIL'이 필요합니다.
화면 코드 확인 방법
•
1. 카페24 쇼핑몰 관리자에 로그인합니다. 쇼핑몰 관리자 로그인 바로가기
•
2. 상단의 [쇼핑몰 어드민 > 쇼핑몰 설정 > 사이트 설정 > "사이트 환경 설정 > 쇼핑몰 환경 설정 > 화면 경로"] 로 이동합니다.
화면 보기열기
•
3. 앱을 위치시키고자 하는 화면의 경로와 화면명을 확인합니다.
•
4. 해당 화면의 코드를 확인합니다.
모듈의 개념 이해
화면을 구성하는 모듈의 개념과, 앱의 UI를 컨트롤하는 방법을 알아봅니다.
목차
모듈과 모듈명
•
모듈은 카페24 쇼핑몰의 프론트 화면을 구성하는 각각의 기능 단위입니다.
•
아래 예시 이미지를 보시면 여러개의 모듈이 블록화되어 화면을 구성하고 있는 것을 확인할 수 있습니다.
쇼핑몰 프론트의 '상품상세' 화면 일부 예시
•
파란색 박스로 표시된 부분이 모듈이며, 각 모듈에는 모듈명이 부여되어 있습니다.
•
만약 '홈 > (대분류) Dresses' 표시 아래에 앱을 위치시키려면, 해당 모듈명(product_headcategory)을 기준으로 하면 됩니다.
Note!
스마트 디자인과 모듈에 대한 자세한 정보는 다음 사이트를 참조하세요.
모듈명 확인 방법
•
1. 카페24 쇼핑몰 관리자에 로그인합니다. 쇼핑몰 관리자 로그인 바로가기
Note!
카페24 회원가입시 생성된 테스트 쇼핑몰 계정으로 로그인하시면 됩니다.
•
2. 상단의 [디자인관리]로 이동하여 [디자인 수정]버튼을 클릭합니다.
•
3.스마트디자인 에디터에서 해당 화면의 HTML 파일을 여시면 다음과 같이 모듈명을 확인하실 수 있습니다.
•
모듈명이 확인되면 아래와 같이 특정 모듈 뒤에 HTML을 추가하여 앱 UI를 컨트롤 할 수 있습니다.
product_headcartegory 모듈 기준 예시
var SAMPLEAPP_FRONT_PRODUCT_DETAIL = function () {
$(".xans-product_headcartegory").after([
//앱 UI를 구현하는 코드(HTML)를 입력합니다.
].join("\n"));
};
if (document.readyState === 'complete') {
SAMPLEAPP_FRONT_PRODUCT_DETAIL();
} else {
window.addEventListener('load', SAMPLEAPP_FRONT_PRODUCT_DETAIL);
}
Note!
•
모듈명 앞에는 prefix인 'xans-'를 붙여서 클래스화 할 수 있습니다.
•
모듈명 대신 HTML Element ID를 기준으로 하는 것도 가능합니다.
•
날개 배너, 레이어 형태 등은 자체적으로 위치를 설정해야 합니다.