@builtbystack/vip-theme-sdk

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

Getting started

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

$3

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

``shell
npm install @builtbystack/vip-theme-sdk
`

$3

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

`html

`

$3

$3

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

`javascript

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

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

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

$3

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

`html


`

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

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

API

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

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

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

$3

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

#### Arguments

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

#### Response

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

#### Example

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


##### npmでの利用

`javascript
// 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.customerPointLogs(25);

// ポイント履歴を表示する
pointLogs.nodes.forEach((log) => {
console.log(${log.title}: ${log.point}ポイント);

// 注文関連のポイント履歴の場合は注文番号も表示
if (log.orderName) {
console.log(注文番号: ${log.orderName});
}
});

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

##### Script Tagでの利用

`javascript


`

$3

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

#### Response

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

#### Example


##### npmでの利用

`javascript
// 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での利用

`javascript


`

$3

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

#### Arguments

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

#### Response

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

#### Example

##### npmでの利用

`javascript
// 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での利用

`javascript



`

$3

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

#### Example

##### npmでの利用

`javascript
// 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での利用

`javascript


`

$3

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

#### Arguments

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

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

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

##### npmでの利用

`javascript
// 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での利用

`javascript



`

$3

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

#### 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での利用

`javascript
// 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, null, 500, 25);

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

##### Script Tagでの利用

`javascript



`

$3

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

#### Arguments

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

#### Response

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

#### Example

##### npmでの利用

`javascript
// 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での利用

`javascript



`

$3

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

#### Arguments

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

#### Response

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

#### Example

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

##### npmでの利用

`javascript
// 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での利用

`javascript


`

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

$3

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

#### Arguments

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

#### Response

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

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

#### Example

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

##### npmでの利用

`javascript
// 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での利用

`javascript


`

productPointMultiple

商品のポイント倍率を取得します。
アプリがインストールされていない場合、エラーがスローされます。

#### Arguments

- id: 倍率を取得する商品のID

#### Response

- multiple (string): 商品の倍率
- productShopifyId (string): 商品のID

商品倍率が設定されていない場合は、multipleは1を返します。

#### Example

特定の商品の商品倍率を取得します。アプリがインストールされていない場合、エラーがスローされます。

##### npmでの利用

`javascript
// 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 productID = "gid://shopify/Product/1234567890";
const pointMultiple = await sdk.productPointMultiple(productID);
// 後続の処置を行う。
`

##### Script Tagでの利用

`javascript


`

$3

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

#### Arguments

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

#### Response

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

#### Example

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

##### npmでの利用

`javascript
// 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での利用

`javascript


`

License

@builtbystack/vip-theme-sdk`はMITライセンスの下でリリースされています。詳細については、LICENSEファイルを参照してください。