@builtbystack/vip-theme-sdk NPM

@builtbystack/vip-theme-sdk

@builtbystack/vip-theme-sdkは、VIPからポイントや会員ランクなどのデータをShopifyのテーマ上から取得することができるJavaScriptライブラリです。

Getting started

このライブラリは、npm経由でインストールするか、スクリプトタグ経由でunpkg.comから読み込むことができます。

npm

以下のコマンドを実行してください。

npm install @builtbystack/vip-theme-sdk

Script Tag

以下のコードを追加してください。

<script src="https://unpkg.com/@builtbystack/vip-theme-sdk@0.0.27/dist/index.umd.js"></script>

SDKのセットアップ

npmでの利用

npmでのご利用はテーマ開発ようのJavascriptのプロジェクトが存在する場合を想定したご利用方法です。

import { VIPAppSDK } from '@builtbystack/vip-theme-sdk';

const sdk = new VIPAppSDK("利用されるストアのURLをここに入れてください")

// Liquidのscript tag内部で利用する場合の例
const sdk = new VIPAppSDK("{{ request.origin }}")

Script Tagでの利用

ScriptTagでの利用は直接Liquidファイル上で実現することを想定したご利用方法です。

<script src="https://unpkg.com/@builtbystack/vip-theme-sdk@0.0.27/dist/index.umd.js"></script>
<script>
  const sdk = new VipApp.VIPAppSDK({{ request.origin | json }});
  // この下にSDKを使用するJavaScriptを記述してください。
</script>

Script Tagで使用される場合、SDKを使用するJavaScriptを別ファイルで管理される場合には、Script Tagでの読み込みが完了した後に使用するように制御してください。

参考: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script

API

以下の記載の関数が利用可能です。

import { VIPAppSDK } from '@builtbystack/vip-theme-sdk';

const sdk = new VIPAppSDK("https://example-store.myshopify.com")

pointLogs

顧客のポイント履歴を取得することができます。顧客がログインしていない状態では機能しません。

Arguments

first(number): 指定された数値までの最初のn個のオブジェクト一覧を返します
after(string | null): 指定されたカーソルのあとに続くオブジェクト一覧を返します

Response

pointLogs:
- nodes(pointLog[]): ポイント履歴の配列
  - id (string): ポイント履歴の識別子
  - point (number): ポイント数
  - title (string): ポイントのタイトル
  - createdAt (any): 作成日時(ISO8601形式)
  - displayExpiredAt (any | null): 有効期限(ISO8601形式)、存在しない場合はnull
  - isExpired (bool): ポイントが失効しているかどうか
- pageInfo: ページネーション情報
  - endCursor (string): 取得した一番最後のオブジェクトのカーソル
  - hasNextPage (bool): 取得可能な続きのページが存在するかどうか

Example

以下の例では1ページ目に25件のポイント履歴を取得し、次のページが存在する場合にendCursorを使って次のページを取得しています。

npmでの利用

// Import the library if you installed it via npm
import { VIPAppSDK } from '@builtbystack/vip-theme-sdk';

const sdk = new VIPAppSDK("https://example-store.myshopify.com")

// ポイントの取得

// 1ページ最大25件のポイント履歴を取得する場合
const { pointLogs } = await sdk.pointLogs(25);

// 次のページが存在する場合、endCursorを渡して次のページを取得する
if (pointLogs.pageInfo.hasNextPage) {
    const { pointLogs: pointLogs2 } = await sdk.pointLogs(25, pointLogs.pageInfo.endCursor);
}
// 後続の処理を行う

Script Tagでの利用

<script src="https://unpkg.com/@builtbystack/vip-theme-sdk@0.0.27/dist/index.umd.js"></script>
<script>
  const sdk = new VipApp.VIPAppSDK({{ request.origin | json }});

  // ポイントの取得
  async function f() {
  // 1ページ最大25件のポイント履歴を取得する場合
  const { pointLogs } = await sdk.pointLogs(25);

  // 次のページが存在する場合、endCursorを渡して次のページを取得する
  if (pointLogs.pageInfo.hasNextPage) {
    const { pointLogs: pointLogs2 } = await sdk.pointLogs(25, pointLogs.pageInfo.endCursor);
  }
  // 後続の処理を行う
  };

  f();
</script>

customerApprovedPoint

顧客が利用できるポイント数を取得することができます。顧客がログインしていない状態では機能しません。

Response

approvedPoint(number): 利用可能なポイント数

Example

npmでの利用

// Import the library if you installed it via npm
import { VIPAppSDK } from '@builtbystack/vip-theme-sdk';

const sdk = new VIPAppSDK("https://example-store.myshopify.com")


const { approvedPoint } = await sdk.customerApprovedPoint();
// 後続の処置を行う。

Script Tagでの利用

<script src="https://unpkg.com/@builtbystack/vip-theme-sdk@0.0.27/dist/index.umd.js"></script>
<script>
  async function f() {
    const { approvedPoint } = await sdk.customerApprovedPoint();
    // 後続の処置を行う。
  };

  f();
</script>

customerPointUse

ポイントを利用するためのディスカウントコードを発行することができます。顧客がログインしていない状態では機能しません。ポイント利用用途のディスカウントコードは顧客ごとに1つしか発行されず、すでに発行されている状態で再度このリクエストを行うと古いディスカウントコードは削除されます。

Arguments

input:
- point(number): 利用するポイント数

Response

point(number): 利用したポイント数
discountCode(string): 利用したポイントに対応する割引コード

Example

npmでの利用

// Import the library if you installed it via npm
import { VIPAppSDK } from '@builtbystack/vip-theme-sdk';

const sdk = new VIPAppSDK("https://example-store.myshopify.com")


const { point, discountCode } = await sdk.customerPointUse({ point: 100 });
// 後続の処置を行う。

Script Tagでの利用

<script src="https://unpkg.com/@builtbystack/vip-theme-sdk@0.0.27/dist/index.umd.js"></script>
<script>
  async function f() {
    const { point, discountCode } = await sdk.customerPointUse({ point: 100 });
    // 後続の処置を行う。
  };

  f();
</script>

customerPointCancel

VIPによってポイント利用用途で発行されている最新のディスカウントコードを削除します。顧客がログインしていない状態では機能しません。

Example

npmでの利用

// Import the library if you installed it via npm
import { VIPAppSDK } from '@builtbystack/vip-theme-sdk';

const sdk = new VIPAppSDK("https://example-store.myshopify.com")


const { point, discountCode } = await sdk.customerPointUse({ point: 100 });

// 100ポイントを使用した割引コードを解除する
await sdk.customerPointCancel();

// 後続の処置を行う。

Script Tagでの利用

<script src="https://unpkg.com/@builtbystack/vip-theme-sdk@0.0.27/dist/index.umd.js"></script>
<script>
  async function f() {
    // 100ポイントを使用した割引コードを解除する
    const { point, discountCode } = await sdk.customerPointUse({ point: 100 });

    // 100ポイントを使用した割引コードを解除する
    await sdk.customerPointCancel();

    // 後続の処置を行う。
  };

  f();
</script>

reward

1件のリワード情報を取得します。顧客がログインしていない状態では機能しません。引数のリワードのIDが不正、またはリワード情報が見つからない場合、エラーがスローされます。

Arguments

id: 取得するリワードのID

Response

id (string): リワードの識別子
title (string): リワードのタイトル
description (string): リワードの説明
point (number): リワードと交換するのに必要なポイント数
hasCustomerEnoughPoint (boolean): 顧客がリワードと交換するのに必要なポイントを持っているかどうか
- image (object): 画像に関する情報
  - url (string): 画像のURL

Example

以下の例では、ログインしている顧客の特定のリワード情報を取得します。

npmでの利用

// Import the library if you installed it via npm
import { VIPAppSDK } from '@builtbystack/vip-theme-sdk';

const sdk = new VIPAppSDK("https://example-store.myshopify.com")


let reward = await sdk.reward("reward-id");
// 後続の処置を行う。

Script Tagでの利用

<script src="https://unpkg.com/@builtbystack/vip-theme-sdk@0.0.27/dist/index.umd.js"></script>
<script>
  async function f() {
    let reward = await sdk.reward("reward-id");
    // 後続の処置を行う。
  };

  f();
</script>

rewards

リワードの一覧を取得することができます。顧客がログインしていない状態では機能しません。

Arguments

first(number): 指定された数値までの最初のn個のオブジェクト一覧を返します
after(string | null): 指定されたカーソルのあとに続くオブジェクト一覧を返します
minPoint(number): 指定した数値以上のポイントが必要なオブジェクト一覧を返します
maxPoint(number): 指定した数値以下のポイントで交換可能なオブジェクト一覧を返します

Response

enabledRewardRules:
- nodes(reward[]): リワードの配列
  - id (string): リワードの識別子
  - title (string): リワードのタイトル
  - description (string): リワードの説明
  - point (number): リワードと交換するのに必要なポイント数
  - hasCustomerEnoughPoint (bool): 顧客がリワードと交換するのに十分なポイントを持っているかどうか
  - image (object): 画像に関する情報
    - url (string): 画像のURL
- pageInfo: ページネーション情報
  - endCursor (string): 取得した一番最後のオブジェクトのカーソル
  - hasNextPage (bool): 取得可能な続きのページが存在するかどうか

Example

以下の例では、特定のポイント範囲（この場合は最小ポイントが100、最大ポイントが500）内のリワードを1ページ目に25件取得し、次のページが存在する場合にendCursorを使用して次のページを取得します。

npmでの利用

// Import the library if you installed it via npm
import { VIPAppSDK } from '@builtbystack/vip-theme-sdk';

const sdk = new VIPAppSDK("https://example-store.myshopify.com")


// 1ページ最大25件のポイント履歴を取得する場合
let { rewardRules } = await sdk.rewards(100, 500, 25);

// 次のページが存在する場合、endCursorを渡して次のページを取得する
if (rewardRules.pageInfo.hasNextPage) {
    const { rewardRules: rewardRules2 } = await sdk.rewards(100, 500, 25, rewardRules.pageInfo.endCursor);
}
// 後続の処置を行う。

Script Tagでの利用

<script src="https://unpkg.com/@builtbystack/vip-theme-sdk@0.0.27/dist/index.umd.js"></script>
<script>
  async function f() {
    // 1ページ最大25件のポイント履歴を取得する場合
    let { rewardRules } = await sdk.rewards(100, 500, 25);

    // 次のページが存在する場合、endCursorを渡して次のページを取得する
    if (rewardRules.pageInfo.hasNextPage) {
      const { rewardRules: rewardRules2 } = await sdk.rewards(100, 500, 25, rewardRules.pageInfo.endCursor);
    }
    // 後続の処置を行う。
    };

  f();
</script>

customerRewardTrade

顧客のポイントとリワードを交換できます。顧客がログインしていない状態では機能しません。引数のリワードのIDが不正、またはリワード情報が見つからない場合エラーがスローされます。ポイントとリワードを交換すると、交換するのに必要になったポイント数分、顧客のポイント数が減少します。

Arguments

input:
- rewardRuleID(string): 交換するリワードの識別子

Response

rewardRule:
- id (string): リワードの識別子
- title (string): リワードのタイトル
- description (string): リワードの説明
- point (number): リワードと交換するのに必要なポイント数
- hasCustomerEnoughPoint (bool): 顧客がリワードと交換するのに十分なポイントを持っているかどうか
- image (object): 画像に関する情報
  - url (string): 画像のURL

Example

npmでの利用

// Import the library if you installed it via npm
import { VIPAppSDK } from '@builtbystack/vip-theme-sdk';

const sdk = new VIPAppSDK("https://example-store.myshopify.com")


const { rewardRule } = await sdk.customerRewardTrade({ rewardRuleID: "reward-id" });
// 後続の処置を行う。

Script Tagでの利用

<script src="https://unpkg.com/@builtbystack/vip-theme-sdk@0.0.27/dist/index.umd.js"></script>
<script>
  async function f() {
    const { rewardRule } = await sdk.customerRewardTrade({ rewardRuleID: "reward-id" });
    // 後続の処置を行う。
  };

  f();
</script>

customerReferralCode

顧客の紹介コードを取得します。顧客がログインしていない状態では機能しません。またはアプリがインストールされていない場合は機能しません。

Arguments

このメソッドは引数を受け取りません。

Response

referralCode (string): 顧客の紹介コード

Example

以下の例では、顧客の紹介コードを取得します。アプリがインストールされていない場合、エラーがスローされます。

npmでの利用

// Import the library if you installed it via npm
import { VIPAppSDK } from '@builtbystack/vip-theme-sdk';

const sdk = new VIPAppSDK("https://example-store.myshopify.com")


const { referralCode } = await sdk.customerReferralCode();
// 後続の処置を行う。

Script Tagでの利用

<script src="https://unpkg.com/@builtbystack/vip-theme-sdk@0.0.27/dist/index.umd.js"></script>
<script>
  async function f() {
    const { referralCode } = await sdk.customerReferralCode();
    // 後続の処置を行う。
  };

  f();
</script>

注意: customerReferralCode メソッドはログインしている顧客のみが使用でき、顧客がログインしていない状態では機能しません。アプリがインストールされていない場合はエラーがスローされます。

customerReferredBy

顧客が他人から紹介されたかどうか、そしてその紹介が注文価格の条件を満たしているかどうかを取得します。顧客がログインしていない状態では機能しません。アプリがインストールされていない場合、エラーがスローされます。

Arguments

このメソッドは引数を受け取りません。

Response

isOrderPriceRequirementCompleted (boolean): 注文価格の条件が満たされているかどうか
referralCode (string): 紹介者の紹介コード

もし顧客が他人から紹介されていない場合は、nullを返します。

Example

以下の例では、紹介者の紹介コードとその紹介が注文価格の条件を満たしているかどうかを取得します。アプリがインストールされていない場合、エラーがスローされます。

npmでの利用

// Import the library if you installed it via npm
import { VIPAppSDK } from '@builtbystack/vip-theme-sdk';

const sdk = new VIPAppSDK("https://example-store.myshopify.com")


const referralInfo = await sdk.customerReferredBy();
// 後続の処置を行う。

Script Tagでの利用

<script src="https://unpkg.com/@builtbystack/vip-theme-sdk@0.0.27/dist/index.umd.js"></script>
<script>
  async function f() {
    const referralInfo = await sdk.customerReferredBy();
    // 後続の処置を行う。
  };

  f();
</script>

customerReferralCodeRegister

顧客が紹介コードを登録することができます。顧客がログインしていない場合機能しません。アプリがインストールされていない場合、エラーがスローされます。引数の紹介コードが不正、または紹介規則が見つからない場合、エラーがスローされます。

Arguments

input (object): 入力パラメータ
- code (string): 登録する紹介コード

Response

isOrderPriceRequirementCompleted (boolean): 注文価格の条件が満たされているかどうか
referralCode (string): 紹介者の紹介コード

Example

以下の例では、顧客が紹介コードを登録します。紹介規則が見つからない場合、エラーがスローされます。

npmでの利用

// Import the library if you installed it via npm
import { VIPAppSDK } from '@builtbystack/vip-theme-sdk';

const sdk = new VIPAppSDK("https://example-store.myshopify.com")


const referralInfo = await sdk.customerReferralCodeRegister({ code: 'abc-ABC' });
// 後続の処置を行う。

Script Tagでの利用

<script src="https://unpkg.com/@builtbystack/vip-theme-sdk@0.0.27/dist/index.umd.js"></script>
<script>
  async function f() {
    const referralInfo = await sdk.customerReferralCodeRegister({ code: 'abc-ABC' });
    // 後続の処置を行う。
  };

  f();
</script>