> For the complete documentation index, see [llms.txt](https://docs.dfinery.ai/developer-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dfinery.ai/developer-guide/platform/web/integration.md). # 연동하기 ## 시작하기 전에 [DFINERY 콘솔](https://console.dfinery.ai/)의 서비스 관리/서비스 정보 페이지에서 데이터 소스 항목에 Web > 루트 도메인을 등록해주셔야합니다. ex) -> dfinery.io 등록
### SDK 지원 브라우저 지원 브라우저는 아래와 같습니다. ``` Chrome, Safari, Samsung Internet, Edge, Whale, Firefox, Opera ``` {% hint style="warning" %} IE(Intenet Explorer)는 지원하지 않습니다. {% endhint %} ## SDK 설치 DFINERY Web SDK는 CDN snippet 또는 npm package 방식으로 설치할 수 있습니다. 이 가이드의 JavaScript 예시는 CDN snippet으로 로드한 전역 `Dfinery` 객체 기준입니다. npm package를 JavaScript 프로젝트에서 사용하는 경우에는 TypeScript 예시와 같이 `import`하고 타입 표기만 제거해 사용합니다. ### CDN snippet으로 설치 빌드 도구 없이 HTML 문서에서 직접 SDK를 로드하는 경우 아래의 snippet을 추가합니다. {% tabs %} {% tab title="JavaScript" %} ```javascript // SDK 3.1.0 설치 !function(_,e){if(void 0!==_&&!_.Dfinery){var d={queue:[]},t=e.createElement("script");t.type="text/javascript",t.async=!0,t.src="//static.dfinery.io/web-sdk/3.1.0/dfn-web-sdk.min.js",t.onload=function(){_.Dfinery.runQueuedFunctions&&_.Dfinery.runQueuedFunctions()};var n=e.getElementsByTagName("script")[0];n.parentNode.insertBefore(t,n);["init","onInitialized","logEvent","setUserProfile","setUserProfiles","setIdentity","setIdentities","resetIdentity","enableSDK","disableSDK"].forEach((function(_){var e=_.split("."),t=e.pop();e.reduce((function(_,e){return _[e]=_[e]||{}}),d)[t]=function(){d.queue.push([_,arguments])}}));const i={LOGIN:"df_login",LOGOUT:"df_logout",SIGN_UP:"df_sign_up",PURCHASE:"df_purchase",REFUND:"df_refund",VIEW_HOME:"df_view_home",VIEW_PRODUCT_DETAILS:"df_view_product_details",ADD_TO_CART:"df_add_to_cart",ADD_TO_WISHLIST:"df_add_to_wishlist",VIEW_SEARCH_RESULT:"df_view_search_result",SHARE_PRODUCT:"df_share_product",VIEW_LIST:"df_view_list",VIEW_CART:"df_view_cart",REMOVE_CART:"df_remove_cart",ADD_PAYMENT_INFO:"df_add_payment_info"},E={ITEMS:"df_items",ITEM_ID:"df_item_id",ITEM_NAME:"df_item_name",ITEM_PRICE:"df_price",ITEM_QUANTITY:"df_quantity",ITEM_DISCOUNT:"df_discount",ITEM_CATEGORY1:"df_category1",ITEM_CATEGORY2:"df_category2",ITEM_CATEGORY3:"df_category3",ITEM_CATEGORY4:"df_category4",ITEM_CATEGORY5:"df_category5",DISCOUNT:"df_discount",TOTAL_REFUND_AMOUNT:"df_total_refund_amount",ORDER_ID:"df_order_id",DELIVERY_CHARGE:"df_delivery_charge",PAYMENT_METHOD:"df_payment_method",TOTAL_PURCHASE_AMOUNT:"df_total_purchase_amount",SHARING_CHANNEL:"df_sharing_channel",SIGN_CHANNEL:"df_sign_channel",KEYWORD:"df_keyword"},f={MALE:"Male",FEMALE:"Female",NON_BINARY:"NonBinary",OTHER:"Other"},r={EXTERNAL_ID:"external_id",EMAIL:"email",PHONE_NO:"phone_no",KAKAO_USER_ID:"kakao_user_id",LINE_USER_ID:"line_user_id",UNIFIED_ID:"unified_id"},o={BIRTH:"df_birth",GENDER:"df_gender",NAME:"df_name",MEMBERSHIP:"df_membership",PUSH_OPTIN:"df_push_optin",PUSH_ADS_OPTIN:"df_push_ads_optin",PUSH_NIGHT_ADS_OPTIN:"df_push_night_ads_optin",SMS_ADS_OPTIN:"df_sms_ads_optin",KAKAO_ADS_OPTIN:"df_kakao_ads_optin"},a={LOG_ENABLE:"logEnable",LOG_LEVEL:"logLevel",SHARE_SUBDOMAIN_COOKIE:"shareSubdomainCookie"},I={DISABLE:0,ERROR:1,WARN:2,INFO:3};_.DFEvent=i,_.DFEventProperty=E,_.DFGender=f,_.DFIdentity=r,_.DFUserProfile=o,_.DFConfig=a,_.DFLogLevel=I,_.Dfinery=d}}(window,document); ``` {% endtab %} {% endtabs %} ### npm package로 설치 번들러나 TypeScript를 사용하는 프로젝트에서는 npm package를 설치한 뒤 코드에서 SDK를 import합니다. npm 방식에서는 SDK 코드가 애플리케이션 번들에 포함되므로 CDN snippet처럼 별도 SDK 파일 로드를 기다리는 queue snippet은 필요하지 않습니다. {% tabs %} {% tab title="npm" %} ```bash npm install @igaworks/dfinery-web-sdk@3.1.0 ``` {% endtab %} {% tab title="yarn" %} ```bash yarn add @igaworks/dfinery-web-sdk@3.1.0 ``` {% endtab %} {% endtabs %} ## SDK 초기화 {% tabs %} {% tab title="JavaScript" %} ```javascript Dfinery.init("SERVICE_KEY"); ``` {% endtab %} {% tab title="TypeScript" %} ```typescript import Dfinery from "@igaworks/dfinery-web-sdk"; async function initializeDfinery(): Promise { await Dfinery.init("SERVICE_KEY"); } void initializeDfinery(); ``` {% endtab %} {% endtabs %} 매개변수는 다음을 의미합니다. * `SERVICE_KEY` : DFINERY 콘솔에서 발급된 서비스키 {% hint style="warning" %} 반드시 설치 스크립트 이후에 초기화 스크립트가 실행되어야 합니다. {% endhint %} npm 또는 TypeScript 환경에서 초기화 직후 다른 SDK API를 호출해야 하는 경우 `await Dfinery.init(...)` 이후에 호출합니다. `init`은 SDK 사용 가능 상태를 준비하는 Promise이며, 모든 백그라운드 전송 완료를 의미하지는 않습니다. 버튼 클릭처럼 사용자가 나중에 실행하는 동작에서 SDK API를 호출하는 경우에는 애플리케이션 시작 구간에서 `Dfinery.init(...)`를 먼저 실행해 둡니다. 단, 초기화가 끝나기 전에 실행될 수 있는 흐름에서는 `await Dfinery.init(...)` 이후에 SDK API를 호출하세요. ### 초기화 이후 바로 SDK API를 호출하는 경우 {% tabs %} {% tab title="TypeScript" %} ```typescript import Dfinery, { DFEvent } from "@igaworks/dfinery-web-sdk"; async function initializeDfinery(): Promise { await Dfinery.init("SERVICE_KEY"); await Dfinery.logEvent(DFEvent.VIEW_HOME); } void initializeDfinery(); ``` {% endtab %} {% endtabs %} CDN snippet 방식에서는 SDK 파일 로드 전에 호출한 함수가 queue에 적재됩니다. 초기화 완료 이후 실행해야 하는 로직은 `onInitialized`에서 처리합니다. ```javascript Dfinery.init("SERVICE_KEY"); Dfinery.onInitialized(function () { Dfinery.logEvent(DFEvent.VIEW_HOME); }); ``` ## SDK 설정 SDK 설정은 `Dfinery.init("SERVICE_KEY", initOptions)` 형태로 전달합니다. 매개변수는 다음을 의미합니다. * `initOptions` : SDK 설정 Dictionary ### SDK 설정 값 | 이름 | 타입 | 기본값 | 설명 | 필수 | | -------------------- | ---------- | ---------------- | ------------------------- | -- | | shareSubdomainCookie | boolean | true | sub domain과 공유되는 쿠키 사용 여부 | X | | logEnable | boolean | true | 로그 활성화 여부 | X | | logLevel | DFLogLevel | DFLogLevel.ERROR | [로그레벨](#log_level) 사용 | X | ### 사용 예시 {% tabs %} {% tab title="JavaScript" %} ```javascript const initOptions = {}; // INFO로 설정시 자세한 로그를 볼수 있습니다. 테스트시 추천합니다. initOptions[DFConfig.LOG_LEVEL] = DFLogLevel.INFO; Dfinery.init("SERVICE_KEY", initOptions); ``` {% endtab %} {% tab title="TypeScript" %} ```typescript import Dfinery, { DFConfig, DFLogLevel } from "@igaworks/dfinery-web-sdk"; async function initializeDfinery(): Promise { const initOptions = { [DFConfig.LOG_LEVEL]: DFLogLevel.INFO, }; await Dfinery.init("SERVICE_KEY", initOptions); } void initializeDfinery(); ``` {% endtab %} {% endtabs %} ### SDK 설정 상수 | 상수 | 값 | 설명 | | --------------------------------- | -------------------- | -------------------- | | DFConfig.LOG\_ENABLE | logEnable | 로그 활성화 여부 | | DFConfig.LOG\_LEVEL | logLevel | 로그 레벨 | | DFConfig.SHARE\_SUBDOMAIN\_COOKIE | shareSubdomainCookie | 서브도메인과 공유되는 쿠키 사용 여부 | ### 로그 레벨 | 상수 | 값 | 설명 | | ------------------ | - | ----------------------- | | DFLogLevel.DISABLE | 0 | 로그 표시 안 함 | | DFLogLevel.ERROR | 1 | Error 로그만 표시 | | DFLogLevel.WARN | 2 | Warn, Error 로그 표시 | | DFLogLevel.INFO | 3 | Error, Warn, Info 로그 표시 | ### 완료 SDK 설치 및 초기화가 완료되었습니다. CDN snippet 방식은 브라우저 개발자도구 콘솔에서 `window.Dfinery` 객체가 생성되어 있는지 확인합니다. npm package 방식은 SDK를 import한 애플리케이션 코드에서 `Dfinery.init("SERVICE_KEY")` 호출이 정상 실행되는지 확인합니다.