ガイド

eSIM ウィジェットを script タグ1つでサイトに追加する方法

Atli ウィジェットは、旅行用 eSIM のストア一式とパートナーコードを script タグ1つに収めます。設置、デザインの変更、売上の計測、サンドボックスでのテストの方法を説明します。

記事の下に Atli eSIM ウィジェットを埋め込み、行き先と価格を一覧表示したブラウザのウェブページと、プランのカードを持つ羽のある青い Atli のマスコット

Atli ウィジェットを使うと、script タグひとつで、あなたのウェブサイトに旅行用 eSIM のストア一式を追加できます。訪問者はあなたのページを離れることなく、行き先を検索し、プランを比較し、支払いを済ませて、eSIM の QR コードを受け取れます。スクリプトにはパートナーコードが含まれており、対象となる購入はあなたのアカウントに紐づけられます。

埋め込みは無料で、ビルドの工程もいりません。カタログ、決済、eSIM のお届けは Atli が担います。設置に必要なのは、コンテナひとつと script タグひとつだけです。

このページでも、本物のウィジェットが動いています。

ページにウィジェットを追加する

partners.heyatli.com にサインインし、連携 を開きます。埋め込みウィジェット のカードに、パートナーコード入りの、サイトに貼るためのコードが表示されます。カスタマイズ を押すと partners.heyatli.com/ja/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 を省くと、ウィジェットは script タグの直後に表示されます。

スクリプトは約17 KB で、ほかに何もインストールする必要はありません。ストアは embed.heyatli.com のフレーム内で読み込まれ、そのフレームからは、あなたのページも、その Cookie やストレージも読み取れません。カード情報は、フレーム内にある 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 には、英字2文字の国コード(jp)、ウィジェットが対応するいずれかの言語での国名(Japan、日本)、地域(europe、south_east_asia)、プラン ID を指定できます。プラン ID を指定すると、そのプランの購入画面が開きます。ウィジェットが行き先を開くのは、有効な一致が見つかった場合だけです。それ以外の場合は、標準のホーム画面を表示します。どちらの場合も、訪問者はすべての行き先を検索できます。

data-favorites を使うと、人気 タブに自分で選んだ行き先を最大32件まで、指定した順番で並べられます。たとえば data-favorites="jp, kr, tw, asia" のように書きます。

ウィジェットの設定

設定はすべて任意です。script タグでは、それぞれが data- 属性になります。JavaScript では同じ名前をキャメルケースで書き、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-consentall、analytics、none のいずれか。Cookie バナーで得た同意の内容に合わせて指定します。
data-envstaging にすると、Atli のサンドボックスでウィジェットを動かします。公開中のページでは指定しないでください。

ウィジェットは en 英語、pt ポルトガル語、es スペイン語、fr フランス語、it イタリア語、de ドイツ語、pl ポーランド語、ru ロシア語、zh 中国語、ko 韓国語、ja 日本語、id インドネシア語、vi ベトナム語、ms マレー語、ar アラビア語の15言語に対応しています。価格は AUD、CAD、EUR、GBP、HKD、JPY、KRW、SGD、TWD、USD、VND の各通貨で表示できます。対応していない値は無視されます。たとえば data-currency="EUROS" と指定した場合は、初期値の USD で表示されます。

シングルページアプリにウィジェットを追加する

script タグはページの読み込み時にウィジェットを初期化しますが、アプリのルーティングの変化には自動で対応しません。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 なら、ウィジェットはエフェクトひとつに収まります。

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 がすべてのエフェクトを実行し、クリーンアップしてから、もう一度実行します。ウィジェットのインスタンスが重複しないよう、クリーンアップ関数に destroy() を入れてください。

CSS でウィジェットのデザインを変える

data-css には、あなたのサイトにあるスタイルシートの、https:// から始まる完全なアドレスを指定します。ウィジェットはそれをフレーム内で自分のスタイルの後に読み込むので、!important を付けなくても、普通のセレクターが優先されます。ファイルの読み込みに失敗した場合、ウィジェットは標準の見た目のままです。

1行だけ、手を出せない部分があります。どの画面も最後に Powered by 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 ウィジェットの同じ日本のページを4通りで表示:標準のライト表示、ダークテーマ、オレンジのボタンとセリフ体フォントの sunset.css、等幅フォントとグレーのボタンの mono.css

CSS でカスタマイズすると、ウィジェットをあなたのウェブサイトのブランドに合わせられます。インターフェースを完全に制御したい場合は Atli API を使えますが、追加の開発が必要です。

ウィジェットのイベントで購入を計測する

ウィジェットはイベントを発行し、あなたのウェブサイトはそれを使って訪問者の操作や購入を追跡できます。購入をアナリティクスに送るには、HeyAtli.init() でマウントして purchase.completed を待ち受けます。このハンドラーは、購入のたびに GA4 の e コマース形式で 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 は e コマースのイベントの前に毎回これを行うよう推奨しています。

ほかに checkout.opened、payment.started、payment.failed などのイベントがあります。ハンドラーは (detail, info) を受け取り、info.action にイベント名が入っているので、widget.on('*', handler) ですべてのイベントを転送できます。すべてのイベントをブラウザのコンソールに出力するには、init() に debug: true を加えるか、script タグに 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 で、ストア本体はフレームがページの表示領域に近づくまで読み込まれません。ウィジェットが記事の終わり近くにある場合は、訪問者がその部分に近づいたときに内容が読み込まれます。
ひとつのページにウィジェットを2つ置けますか?
置けます。それぞれに専用のコンテナと script タグを用意するか、コンテナごとに HeyAtli.init() を一度ずつ呼び出してください。