가이드

웹사이트에 eSIM 위젯 넣기: 스크립트 태그 하나면 됩니다

Atli 위젯은 여행용 eSIM 스토어 전체와 파트너 코드를 스크립트 태그 하나에 담습니다. 설치, 스타일 변경, 판매 추적, 샌드박스 테스트 방법을 정리했습니다.

글 아래에 들어간 Atli eSIM 위젯이 여행지와 가격을 보여 주는 브라우저 속 웹페이지와 요금제 카드를 든 날개 달린 파란색 Atli 마스코트

Atli 위젯을 사용하면 스크립트 태그 하나로 웹사이트에 여행용 eSIM 스토어 전체를 추가할 수 있습니다. 방문자는 내 페이지를 떠나지 않고도 여행지를 검색하고, 요금제를 비교하고, 결제한 뒤 eSIM QR 코드를 받을 수 있습니다. 스크립트에 파트너 코드가 포함되어 있어, 대상이 되는 구매는 내 계정의 실적으로 잡힙니다.

넣는 데 비용이 들지 않고 빌드 단계도 필요 없습니다. 요금제 카탈로그와 결제, eSIM 전달은 Atli가 맡습니다. 설치에는 컨테이너 하나와 스크립트 태그 하나만 있으면 됩니다.

이 페이지에서 실제 위젯을 써 볼 수 있습니다.

페이지에 위젯 넣기

partners.heyatli.com에 로그인해 연동을 여세요. 임베드 위젯 카드에 파트너 코드가 들어간 내 사이트용 코드가 있습니다. 맞춤 설정을 누르면 partners.heyatli.com/ko/dev/atli-widget의 위젯 빌더가 열리고, 그곳에서 모든 설정을 바꾼 뒤 코드를 다시 복사할 수 있습니다.

내 사이트용 코드와 미리 보기, 맞춤 설정 버튼이 있는 partners.heyatli.com 연동 페이지의 임베드 위젯 카드

코드를 직접 추가하려면 YOUR_CODE를 내 파트너 코드로 바꾸세요.

HTML
<div id="heyatli-esim-checkout-container"></div>
<script
  src="https://embed.heyatli.com/embed.js"
  data-atli-widget
  data-target="#heyatli-esim-checkout-container"
  data-referral="YOUR_CODE"
  defer
></script>

페이지 HTML에서 스토어가 나타날 자리에 붙여 넣으세요. 위젯은 컨테이너 너비를 꽉 채우고, 높이는 보여 주는 내용에 맞춰 늘어납니다. 따로 정할 높이는 없습니다. <div>와 data-target을 빼면 위젯은 스크립트 태그 바로 뒤에 나타납니다.

스크립트는 약 17 KB이고 따로 설치할 것이 없습니다. 스토어는 embed.heyatli.com에서 불러오는 프레임 안에 열리며, 이 프레임은 내 페이지와 그 쿠키, 스토리지를 읽을 수 없습니다. 카드 정보는 프레임 안에 있는 Stripe 결제 폼에 입력됩니다.

특정 여행지로 열기

특정 국가를 다루는 페이지에서는 그 여행지의 요금제를 보여 주도록 위젯을 설정할 수 있습니다. 이 예시는 독일어 가이드에 넣을 위젯을 일본 요금제로 열고 가격을 유로로 보여 줍니다.

HTML
<div id="japan-esim"></div>
<script
  src="https://embed.heyatli.com/embed.js"
  data-atli-widget
  data-target="#japan-esim"
  data-referral="YOUR_CODE"
  data-destination="jp"
  data-lang="de"
  data-lang-priority="widget"
  data-currency="EUR"
  defer
></script>
독일어와 유로 가격으로 일본 페이지를 연 Atli 위젯: 5일부터 30일까지의 무제한 요금제와 각 요금제의 eSIM kaufen 버튼

data-destination에는 두 글자 국가 코드(jp), 위젯이 지원하는 아무 언어로 쓴 국가 이름(Japan, 日本), 지역(europe, south_east_asia), 요금제 ID를 넣을 수 있습니다. 요금제 ID를 넣으면 그 요금제의 결제 화면이 열립니다. 위젯은 유효한 일치 항목을 찾았을 때만 여행지를 엽니다. 그렇지 않으면 기본 홈 화면을 표시합니다. 어느 쪽이든 방문자는 모든 여행지를 검색할 수 있습니다.

data-favorites는 인기 탭을 내가 고른 여행지로 최대 32개까지 채우고, 적은 순서 그대로 보여 줍니다. 예를 들면 data-favorites="jp, kr, tw, asia"처럼 씁니다.

위젯 설정

모든 설정은 선택 사항입니다. 스크립트 태그에서는 각 설정이 data- 속성이고, JavaScript에서는 같은 이름을 camelCase로 씁니다. data-lang-priority는 langPriority가 됩니다.

속성하는 일
data-referral파트너 코드입니다. 구매한 신규 고객이 내 코드에 연결됩니다.
data-destination특정 여행지나 요금제로 엽니다.
data-favorites인기 탭에 넣을 여행지를 쉼표로 구분해 최대 32개까지 적습니다.
data-lang위젯 언어입니다. 없으면 방문자의 브라우저 언어를 씁니다.
data-lang-prioritywidget으로 두면 방문자가 다른 언어를 골라도 지정한 언어를 유지하고 언어 메뉴를 숨깁니다.
data-currency가격 표시와 결제에 쓰는 통화입니다. 기본값은 USD입니다.
data-currency-prioritywidget으로 두면 방문자가 다른 통화를 골라도 지정한 통화를 유지합니다.
data-themelight 또는 dark입니다. 없으면 방문자 기기의 설정을 따릅니다.
data-theme-prioritywidget으로 두면 지정한 테마를 유지하고 테마 설정을 숨깁니다.
data-css위젯에 적용할 내 스타일시트의 https:// 주소입니다.
data-boot방문자 본인의 화면 중 하나로 엽니다. esims, credits, vouchers, refer, settings, payment-methods, groups, profile 중에서 고릅니다. esim은 공유 eSIM의 설치 페이지를 계정 없이 엽니다. 어느 eSIM인지는 data-lpa에 넣은 코드로 정해집니다.
data-anonymous-cardstrue로 두면 로그인하지 않은 방문자도 이 브라우저에 카드를 저장할 수 있습니다. 기본값은 꺼짐입니다.
data-stripe-linkfalse로 두면 결제 폼에서 Stripe Link를 뺍니다.
data-analyticsoff로 두면 위젯이 자체 분석 도구를 불러오지 않습니다.
data-consent쿠키 배너에서 받은 동의에 맞춰 all, analytics, none 중 하나를 넣습니다.
data-envstaging으로 두면 위젯이 Atli 샌드박스에서 돌아갑니다. 실제 페이지에서는 빼세요.

위젯은 15개 언어를 지원합니다. en 영어, pt 포르투갈어, es 스페인어, fr 프랑스어, it 이탈리아어, de 독일어, pl 폴란드어, ru 러시아어, zh 중국어, ko 한국어, ja 일본어, id 인도네시아어, vi 베트남어, ms 말레이어, ar 아랍어입니다. 통화는 AUD, CAD, EUR, GBP, HKD, JPY, KRW, SGD, TWD, USD, VND를 지원합니다. 지원하지 않는 값은 무시됩니다. 예를 들어 data-currency="EUROS"로 지정하면 기본값인 USD로 표시됩니다.

싱글 페이지 앱에 위젯 넣기

스크립트 태그는 페이지가 로드될 때 위젯을 초기화하지만, 앱의 라우팅 변경에는 자동으로 반응하지 않습니다. React, Vue, Next.js처럼 새로고침 없이 페이지를 바꾸는 앱에서는 HTML에서 스크립트를 한 번만 불러오고 위젯은 코드에서 마운트하세요.

HTML
<script src="https://embed.heyatli.com/embed.js"></script>
JavaScript
const widget = HeyAtli.init({
  target: '#esim',
  referral: 'YOUR_CODE',
  destination: 'jp',
  lang: 'de',
  currency: 'EUR',
});

// Change settings later without rebuilding the frame
widget.update({ destination: 'th' });

// Remove it when the page goes away
widget.destroy();

target에는 CSS 선택자나 요소를 넘깁니다. update()는 넘긴 값을 현재 설정에 합치며 프레임을 다시 불러오지 않습니다. React에서는 위젯을 Effect 안에 넣으면 됩니다.

JSX
import { useEffect, useRef } from 'react';

export function EsimStore({ destination }) {
  const ref = useRef(null);

  useEffect(() => {
    const widget = window.HeyAtli.init({
      target: ref.current,
      referral: 'YOUR_CODE',
      destination,
    });
    return () => widget.destroy();
  }, [destination]);

  return <div ref={ref} />;
}

개발 환경에서 React의 Strict Mode는 모든 Effect를 실행하고, 클린업한 다음, 다시 실행합니다. 위젯 인스턴스가 중복되지 않도록 클린업 함수에 destroy()를 넣으세요.

CSS로 위젯 스타일 바꾸기

data-css에 내 사이트에 있는 스타일시트의 https:// 전체 주소를 넣으세요. 위젯은 자체 스타일을 적용한 뒤 프레임 안에서 이 파일을 불러오므로, !important 없이 일반 선택자만으로도 덮어쓸 수 있습니다. 파일을 불러오지 못하면 위젯은 기본 모양을 유지합니다.

손댈 수 없는 줄이 하나 있습니다. 모든 화면 맨 아래에 Atli 제공 | 고객지원 푸터가 있고, 내 스타일시트로는 이 푸터의 모양을 바꾸거나 숨길 수 없습니다. 푸터를 숨기거나, 흐리게 하거나, 잘라 내거나, 가리는 스타일시트는 제거되고, 위젯은 그 방문이 끝날 때까지 기본 모양으로 돌아가며, 브라우저 콘솔에 그 이유가 나옵니다.

먼저 위젯의 CSS 변수부터 바꾸세요. 방문자에게는 라이트 테마와 다크 테마 중 어느 쪽이든 보일 수 있으니 두 테마 모두 변수를 지정하세요.

CSS
.atli-widget {
  --atli-font-family: 'Inter', system-ui, sans-serif;
  --atli-color-accent: #0f766e;
  --atli-color-accent-hover: #115e59;
  --atli-color-accent-text: #ffffff;
  --atli-radius-md: 6px;
}

.atli-widget[data-theme='dark'] {
  --atli-color-accent: #2dd4bf;
  --atli-color-accent-hover: #5eead4;
  --atli-color-accent-text: #042f2e;
}

sunset.css와 mono.css는 자주 쓰는 변수를 모두 주석과 함께 담은 예제입니다. 카드 입력란은 Stripe 자체 프레임 안에 있어서 어떤 스타일시트도 닿지 않습니다. 그 대신 위젯이 결제 폼을 만들 때 강조색, 글자색, 배경색과 글꼴, 모서리 반경을 Stripe에 넘겨줍니다.

Atli 위젯의 같은 일본 페이지를 네 가지 모습으로: 기본 밝은 테마, 다크 테마, 주황색 버튼과 세리프 글꼴의 sunset.css, 고정폭 글꼴과 회색 버튼의 mono.css

CSS로 위젯을 내 웹사이트의 브랜드에 맞출 수 있습니다. 인터페이스를 완전히 직접 제어하려면 Atli API를 사용하세요. 다만 추가 개발이 필요합니다.

위젯 이벤트로 구매 추적하기

위젯은 이벤트를 보내며, 내 웹사이트에서 이 이벤트로 방문자의 활동과 구매를 추적할 수 있습니다. 구매를 분석 도구로 보내려면 HeyAtli.init()으로 위젯을 마운트하고 purchase.completed 이벤트를 받으세요. 이 핸들러는 구매를 하나씩 GA4 전자상거래 형식으로 Google Tag Manager에 넘깁니다.

JavaScript
const widget = HeyAtli.init({ target: '#esim', referral: 'YOUR_CODE' });

widget.on('purchase.completed', function (detail) {
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({ ecommerce: null });
  window.dataLayer.push({
    event: 'purchase',
    ecommerce: {
      transaction_id: detail.transactionId,
      value: detail.value,
      currency: detail.currency,
      items: detail.items,
    },
  });
});

items는 GA4 상품 형식으로 오므로 dataLayer에 그대로 넣으면 됩니다. value는 통화의 기본 단위로 오기 때문에 1299가 아니라 12.99로 들어옵니다. 첫 번째 push는 이전 ecommerce 객체를 비웁니다. Google은 전자상거래 이벤트를 보낼 때마다 먼저 이렇게 하라고 권장합니다.

이 밖에 checkout.opened, payment.started, payment.failed 같은 이벤트도 있습니다. 핸들러는 (detail, info)를 받고 info.action에 이벤트 이름이 들어 있으므로, widget.on('*', handler) 하나로 모든 이벤트를 넘길 수 있습니다. 모든 이벤트를 브라우저 콘솔에 기록하려면 init()에 debug: true를 넣거나 스크립트 태그에 data-debug="true"를 넣으세요.

이벤트는 Atli 허용 목록에 있는 도메인에만 전달됩니다. heyatli.com과 localhost는 목록에 있으므로 내 컴퓨터에서 개발할 수 있습니다. localhost에서 잘 되던 핸들러가 실제 사이트에서 이벤트를 못 받는 것도 이 때문입니다. 도메인 추가는 [email protected]에 요청하세요. 이벤트를 추적할 수 없는 경우에도 위젯은 구매를 처리할 수 있습니다.

샌드박스에서 테스트하기

data-env="staging"을 넣거나 HeyAtli.init()에 env: 'staging'을 넣으면 위젯이 Atli 샌드박스에서 돌아갑니다. 모서리에 샌드박스 태그가 보이고, 테스트 배너에 파트너 코드가 흐리게 표시되므로 페이지가 코드를 제대로 읽었는지 확인할 수 있습니다. 결제는 Stripe 테스트 카드 4242 4242 4242 4242로 하고, 유효기간은 미래 날짜 아무것이나, 보안 코드는 아무 숫자나 넣으면 됩니다. 샌드박스 계정은 실제 계정과 별개입니다. 샌드박스 eSIM은 테스트용 통신사에서 나오므로 휴대폰에 설치할 수 없고, 샌드박스 판매는 수익이 되지 않습니다.

위젯은 기본적으로 프로덕션 환경을 사용합니다. 샌드박스는 테스트 결제만 받으므로 공개하기 전에 data-env="staging"을 빼세요.

위젯 판매가 실적으로 잡히는 방식

위젯에서 구매한 방문자는 로그인하거나 결제할 때 내 코드에 연결됩니다. 다만 다른 파트너의 코드나 이전 구매가 먼저 있었다면 연결되지 않습니다. 위젯은 방문자의 브라우저에 코드를 72시간 동안 기억하므로 다음 날 돌아온 사람도 실적으로 잡힙니다. 첫 구매 뒤에는 연결이 영구적이고, 같은 Atli 계정에서 이후에 하는 구매도 내 실적이 됩니다.

가격은 Atli 스토어와 같고, 내 코드에 붙은 할인은 결제 화면에 표시됩니다. 수익과 정산은 Atli 제휴 프로그램이 수익을 지급하는 방식에서 다룹니다.

자주 묻는 질문

Atli 위젯을 쓰는 데 비용이 드나요?
아니요. 넣는 데 비용이 들지 않고, 결제와 eSIM 전달은 Atli가 맡습니다. 방문자가 구매한 금액에서 수익 배분을 받습니다.
Stripe 계정이 따로 있어야 하나요?
아니요. 위젯은 자체 프레임 안에서 Atli의 Stripe 계정으로 결제를 받으므로 카드 정보가 내 사이트에 닿지 않습니다. 구매자의 카드 명세서에는 Atli 이름이 찍힙니다.
방문자가 위젯에서 바로 eSIM을 설치할 수 있나요?
네. 결제 후 방문자는 eSIM QR 코드, iPhone과 Android용 설치 링크, 수동 설치에 필요한 정보를 받습니다. 휴대폰에서 거치는 단계는 iPhone과 Android 설치 가이드에 정리되어 있습니다.
위젯을 내가 다루는 나라로만 제한할 수 있나요?
일부만 가능합니다. data-destination을 쓰면 특정 여행지 화면으로 열리고, data-favorites로 인기 탭을 내가 고른 여행지 최대 32개로 채울 수 있습니다. 그래도 방문자는 전체 카탈로그를 검색할 수 있습니다.
위젯 때문에 페이지가 느려지나요?
로드할 때는 느려지지 않습니다. 로더는 약 17 KB이고, 스토어 자체는 프레임이 화면에 보이는 영역 가까이 올 때까지 기다립니다. 위젯이 글 끝부분에 있다면 방문자가 그 부분에 가까워질 때 위젯 내용을 불러옵니다.
한 페이지에 위젯을 두 개 넣을 수 있나요?
네. 위젯마다 컨테이너와 스크립트 태그를 따로 두거나, 컨테이너마다 HeyAtli.init()을 한 번씩 호출하세요.