フィールドリファレンス

このページでは、Fanplayr製品カタログでサポートされているすべてのフィールドについて説明します。このページを使用して、Fanplayrがどのような製品データを扱えるか、および各フィールドがどのように構造化されるべきかを理解してください。

どこから始めればよいかわからない場合

カタログ形式が初めての場合は、まず概要をお読みください。PRIMARY/VARIANT製品モデルや最も重要なフィールドなどの主要な概念を説明しています。

Product

Productオブジェクトは、カタログ内の各アイテムのトップレベルの構造です。以下のTypeScriptインターフェースは、開発者に全体像を素早く提供します。型にカーソルを合わせると詳細が表示されます。非技術系の読者は、以下のフィールドの説明に直接スキップしてください。

interface Product {
  id: string; // required
  type?: Type;
  primaryProductId?: string;
  categories: string[]; // required
  title: string; // required
  brands?: string[];
  description?: string;
  languageCode?: string;
  priceInfo: PriceInfo; // required
  availability?: Availability;
  availableQuantity?: number;
  uri: string; // required
  images?: Image[];
  audience?: Audience;
  colorInfo?: ColorInfo;
  sizes?: string[];
  materials?: string[];
  patterns?: string[];
  conditions?: string[];
}

例

有効なProductオブジェクトの完全な例：

{
  "id": "805371A",
  "type": "PRIMARY",
  "categories": ["Women > Shoes", "Sports & Fitness > Shoes"],
  "title": "Red Shoes",
  "description": "Fancy red shoes",
  "brands": ["Designer Brand"],
  "availability": "IN_STOCK",
  "availableQuantity": 30,
  "languageCode": "en",
  "priceInfo": {
    "price": 89.99,
    "originalPrice": 119.99,
    "currencyCode": "USD"
  },
  "uri": "https://www.store.com/shoes/red-shoes",
  "images": [
    {
      "uri": "https://www.store.com/images/805371.jpg",
      "width": 500,
      "height": 500
    }
  ]
}

上記の例には読みやすさのために改行が含まれています。カタログファイルでは、各製品は単一のJSONエンコードされた行である必要があります。ファイルはUTF-8でエンコードされている必要があります。

フィールド

id

• 型: string
• 必須
• 最大サイズ: 128バイト

カタログ内でこの製品を一意に識別するID。同じカタログ内の2つの製品が同じidを共有することはできません。

この値は、Fanplayr統合で追跡される製品IDと一致する必要があります。これは、カタログデータを製品ページビューや購入などの買い物客の行動と関連付けるために使用されます。

type

• 型: enum Type
• デフォルト: primaryProductIdから推論

この製品がトップレベルの製品 (PRIMARY) であるか、そのバリエーション (VARIANT) であるかを示します。値の完全なリストについては、Typeを参照してください。

ほとんどの場合、このフィールドは省略できます。FanplayrはprimaryProductIdに基づいて正しい値を推論します。

• primaryProductIdが存在しない場合、またはidと等しい場合は'PRIMARY'にデフォルト設定されます。
• primaryProductIdがidと異なる場合は'VARIANT'にデフォルト設定されます。

primaryProductId

• 型: string

このバリアントが属するPRIMARY製品のid。バリアントを親製品の下にグループ化するために使用されます。

• PRIMARY製品の場合：空にするか、idと同じ値に設定します。
• VARIANT製品の場合：親PRIMARY製品のidに設定する必要があります。

categories

• 型: string[]
• 必須（少なくとも1つの項目）
• 最大サイズ: 1,000バイト（JSONエンコード時）

この製品が属するカテゴリ。1つの製品は複数のカテゴリに属することができます。末端カテゴリだけでなく、完全なカテゴリパスを提供することで、推奨および検索の品質が大幅に向上します。

階層レベルを区切るには>を使用します。カテゴリ名に>が含まれる場合は、"|"などの別の文字に置き換えてください。

"categories": [
  "Shoes & Accessories > Shoes",
  "Sports & Fitness > Athletic Clothing > Shoes"
]

title

• 型: string
• 必須
• 最大サイズ: 500バイト

ストアフロントに表示される製品名。この値は、買い物客に表示される推奨ウィジェットに表示されるため、ストアフロントと正確に一致する必要があります。

brands

• 型: string[]
• 最大サイズ: 1,000バイト（JSONエンコード時）

この製品に関連付けられたブランド。ブランドを考慮したフィルタリングと推奨機能を実現するために使用されます。必要に応じて複数のブランドをサポートします。

description

• 型: string
• 最大サイズ: 500バイト

製品のプレーンテキストの説明。推奨の関連性を向上させるために使用されます。適切な説明を提供することで、Fanplayrが製品をよりよく理解するのに役立ちます。

languageCode

• 型: string

titleやdescriptionなどのテキストフィールドで使用される言語。有効なBCP 47言語タグ（例："en"、"fr"、"de")である必要があります。

priceInfo

• 型: オブジェクト PriceInfo
• 必須

現在の価格、元の価格、通貨を含むこの製品の価格情報。詳細については、PriceInfoを参照してください。

availability

• 型: enum Availability
• デフォルト: 'IN_STOCK'

製品の現在の在庫状況。Fanplayrはこのフィールドを使用して、買い物客が購入できない製品を推奨しないようにします。値の完全なリストについては、Availabilityを参照してください。

availableQuantity

• 型: number

現在在庫のあるユニット数。

uri

• 型: string
• 必須

製品詳細ページの正規URL。推奨ウィジェットで製品が表示されたときのリンク先として使用されます。

images

• 型: オブジェクト配列 Image

この製品の画像リスト。製品画像は推奨ウィジェットに直接表示されるため、正確で高品質な画像を提供することを強くお勧めします。画像は少なくとも500×500pxである必要があります。詳細については、Imageを参照してください。

audience

• 型: オブジェクト Audience

この製品の対象読者。対象読者データを提供することで、Fanplayrはより関連性の高い推奨を提供できます。例えば、女性カテゴリページで男性向け製品を推奨しないようにすることができます。詳細については、Audienceを参照してください。

colorInfo

• 型: オブジェクト ColorInfo

製品の色情報。特にファッションおよびアパレルストアにとって価値があります。このフィールドを提供することで、色ベースのフィルタリングが可能になり、推奨が改善され、製品推奨ウィジェットにカラーチップを表示できるようになります。詳細については、ColorInfoを参照してください。

sizes

• 型: string[]
• 最大: 20個の値

この製品で利用可能なサイズ。異なるサイズシステムやサイズタイプを表現するには、[[size_system:]size_type:]size_value]の形式を使用します。

• "US:MENS:M" — サイズシステム US、サイズタイプ MENS、サイズ値 M
• "GIRLS:27" — サイズシステムなし、サイズタイプ GIRLS、サイズ値 27
• "32 inches" — サイズシステムまたはタイプなし、サイズ値 32 inches

materials

• 型: string[]
• 最大: 20個の値

この製品が作られている素材（例："leather"、"cotton"、"wood")。

patterns

• 型: string[]
• 最大: 20個の値

製品のパターンまたはグラフィックプリント（例："striped"、"polka dot"、"paisley")。

conditions

• 型: string[]
• 最大: 1つの値

製品の状態。他のフィールドとの一貫性のために配列として定義されていますが、サポートされる値は1つだけです。可能な限り標準値を使用してください。

• "new"
• "refurbished"
• "used"

---

タイプ

以下のタイプは、Productオブジェクト内のフィールドによって参照されます。

Type

製品のタイプ。この製品がトップレベルのアイテムであるか、別の製品のバリエーションであるかを決定します。

値	説明
"PRIMARY"	トップレベルの商品です。PRIMARY商品は、その下に複数のVARIANT商品をグループ化できます。
"VARIANT"	PRIMARY商品のバリエーションです。バリアントは通常、親商品とタイトルやブランドなどの属性を共有しますが、サイズ、色、価格などのプロパティが異なります。

PriceInfo

製品の価格情報。

interface PriceInfo {
  currencyCode: string; // required
  price: number; // required
  originalPrice?: number;
  cost?: number;
}

currencyCode

• 型: string
• 必須

このオブジェクト内のすべての価格に対応するISO 4217の3文字通貨コード（例："USD"、"AUD"、"GBP")。

price

• 型: number
• 必須

製品の現在の販売価格。これは買い物客に表示され、推奨ウィジェットで使用される価格です。

originalPrice

• 型: number

割引前の製品の価格。省略またはゼロの場合、priceの値がデフォルトとなります。提供される場合、originalPriceはprice以上である必要があります。このフィールドを提供することで、Fanplayrはセール品や割引製品を特定し、ターゲットにすることができます。

cost

• 型: number

この製品の原価。粗利益の報告のために内部で使用されます。この値が買い物客に表示されることはありません。

Availability

製品の在庫状況。Fanplayrはこれを使用して、買い物客が購入できない製品を推奨しないようにします。

• デフォルト: "IN_STOCK"

値	説明
"IN_STOCK"	商品は現在購入可能です。
"OUT_OF_STOCK"	商品は現在利用できません。
"PREORDER"	商品はまだリリースされていませんが、予約購入可能です。
"BACKORDER"	商品は一時的に在庫切れですが、バックオーダー可能です。

Image

製品に関連付けられた画像。画像は推奨ウィジェットに直接表示されます。画像は少なくとも500×500pxである必要があります。

interface Image {
  uri: string; // required
  width?: number;
  height?: number;
}

uri

• 型: string
• 必須

画像のURL。最大長5,000文字の有効なUTF-8エンコードされたURIである必要があります。

width

• 型: number

画像の幅（ピクセル単位）。

height

• 型: number

画像の高さ（ピクセル単位）。

Audience

製品の対象読者。推奨の関連性を向上させるために使用されます。

interface Audience {
  genders?: Gender[];
  ageGroups?: AgeGroup[];
}

genders

• 型: ('male' | 'female' | 'unisex')[]
• 最大: 5つの値

この製品が対象とする性別。可能な限り標準値を使用してください。

• "male"
• "female"
• "unisex"

ageGroups

• 型: ('newborn' | 'infant' | 'toddler' | 'kids' | 'adult')[]
• 最大: 5つの値

この製品が対象とする年齢層。可能な限り標準値を使用してください。

• "newborn" — 生後3ヶ月まで
• "infant" — 生後3ヶ月から12ヶ月
• "toddler" — 1歳から5歳
• "kids" — 5歳から13歳
• "adult" — 通常はティーンエイジャー以上

ColorInfo

製品の色情報。特にファッションおよびアパレルストアにとって価値があります。このフィールドを提供することで、色ベースのフィルタリングが可能になり、推奨が改善され、製品推奨ウィジェットにカラーチップを表示できるようになります。

interface ColorInfo {
  colorFamilies?: string[];
  colors?: string[];
}

colorFamilies

• 型: string[]
• 最大: 5つの値

この製品が属する広範な色のファミリー。通常、製品には1つの色ファミリーしかありません。複数の値ではなく、適切な場合は"Mixed"を使用してください。

可能な限り標準値を使用してください。

"Red" "Pink" "Orange" "Yellow" "Purple" "Green" "Cyan" "Blue" "Brown" "White" "Gray" "Black" "Mixed"

colors

• 型: string[]
• 最大: 75個の値

ストアフロントに表示される、この製品の特定の色名（例："Midnight Navy"、"Rose Gold")。これらは標準のcolorFamiliesの値とは異なる場合があります。通常、製品には1つの色しかありません。複数の値ではなく、適切な場合は"Mixed"を使用してください。