# 메타필드 동기화

이 가이드에서는 Tipo 앱에서 Source store의 메타필드를 Destination store로 동기화하는 방법을 설명합니다.

### ℹ️ 메타필드란?

* **상품 메타필드**
* **옵션 메타필드** (활성화한 경우)

Tipo 앱은 다음 항목의 메타필드를 동기화할 수 있습니다.

* 소재, 사이즈 표, 사양
* 커스텀 배지(예: “best\_seller”)
* 테마/앱에서 사용하는 추가 상품 정보

메타필드는 Shopify에서 다음과 같은 추가 상품 데이터를 저장하는 데 사용하는 커스텀 필드입니다.

***

### ✅ **지원되는 메타필드 유형**

* 여러 줄 텍스트
* 리치 텍스트
* 정수
* 소수
* 날짜 및 시간
* 날짜
* 치수
* 부피
* 무게
* 참 또는 거짓
* 평점
* URL
* 금액
* 링크
* JSON

🚫 **아직 지원되지 않음:**\
참조 유형(예: 상품 참조, 컬렉션 참조)은 현재 지원되지 않습니다.

***

### 🛠️ 1단계: Source Store에서 메타필드 구성

1. 앱을 열고 > **Settings**를 클릭한 다음 > **Share Metafields**를 켭니다.
2. 공유하려는 리소스를 선택합니다.
   * **Product resource** – 상품 메타필드를 공유합니다.
   * **Variant resource** – 옵션 메타필드를 공유합니다.
3. 공유할 메타필드를 제한하려면 특정 메타필드 정의를 추가합니다.
   * **Browse metafields** 아이콘을 클릭하거나,
   * 다음 형식으로 메타필드 정의를 입력합니다.

     ```
     namespace.key
     ```

예:

     ```
     custom.materialseo.titlespecifications.weight
     ```
4. Click **Save** to update the changes

<figure><img src="/media/4360c99527c6a4de655c.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

<figure><img src="/media/7a7d4dfafe848ed0a876.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

***

### 🛠️ 2단계: Destination Store에서 메타필드 구성

1. 앱을 열고 > **Stores**를 클릭한 다음 > Source store URL을 클릭하여 연결 상세 정보를 엽니다.

<figure><img src="/media/b99e7e334515ad4e086d.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

2. **Metafields sync**를 켭니다.
3. 동기화할 항목을 선택합니다.

**Allow data**에서 하나 또는 둘 다 선택합니다.

* **Product Resource** → 상품 메타필드 동기화
   * **Variant Resource** → 옵션 메타필드 동기화
4. 오른쪽의 검색 아이콘을 클릭하여 지원되는 모든 메타필드를 확인한 다음 > **Select valid metafield to sync** 버튼을 클릭합니다.&#x20;

<figure><img src="/media/4360c99527c6a4de655c.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

<figure><img src="/media/7a7d4dfafe848ed0a876.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

5. **Save**를 클릭하여 변경 사항을 저장합니다.

***

### &#x20;🔄 동기화 중에 일어나는 일

#### **1) Destination store에 메타필드 정의가 없는 경우**

앱이 (필요한 경우) Destination store에 메타필드 정의를 자동으로 생성합니다.

생성된 후에는 동기화된 메타필드 값이 Destination store의 상품/옵션에 표시됩니다.

#### **2) 메타필드가 존재하지만 “구조화”되지 않은 경우(비구조화 메타필드)**

경우에 따라 Destination store에서 완전히 정의/구조화되지 않았더라도 메타필드가 동기화될 수 있습니다.

Shopify Admin에서 확인하려면:

* 스토어 **Settings → Metafields and metaobjects**를 엽니다.
* **Product**(또는 **Variant**)를 선택합니다.
* **View unstructured metafields**를 엽니다.

💡 팁: 나중에 이 메타필드를 직접 정의/구조화하면 스토어 데이터를 깔끔하고 일관되게 유지할 수 있습니다.

<figure><img src="/media/755ea231da077f6819c8.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

#### **3) Source store에 값이 없으면 Destination의 값을 덮어쓰지 않습니다**

Destination에 메타필드가 있지만 Source 값이 비어 있는 경우, Tipo Sync는 Destination 값을 덮어쓰지 않습니다.

#### **4) 데이터 유형이 일치해야 합니다(매우 중요)**

메타필드 데이터 유형은 Source와 Destination 간에 정확히 일치해야 합니다.

데이터 유형 불일치 예시:

* `single_line_text_field` 대 `multi_line_text_field`
* `number_integer` 대 `number_decimal`
* `product_reference` 대 `text`

⚠️ 데이터 유형이 일치하지 않으면 동기화가 실패하거나 해당 메타필드를 건너뛸 수 있습니다.

***

### 📌 예시: 상품 메타필드 동기화 – “Material”

앱을 사용하여 **Material**(예: “Cotton”, “Leather”, “Wool”)이라는 **커스텀 상품 메타필드**를 **Source Store**에서 **Destination Store**로 동기화하려고 합니다.

#### **1단계: Shopify에서 메타필드 정의**

**Source Store**에서:

1. **Shopify Admin >** 스토어 **Settings > Metafields and metaobjects**로 이동하여 > **Product**(또는 **Variant**)를 선택합니다.
2. (아직 생성되지 않았다면) **Add definition**을 클릭한 다음 > 메타필드 정의를 입력합니다.
   * **Name**: Material
   * **Namespace**: `custom`
   * **Key**: `material`
   * **Type**: Single line text

\=>  그러면 전체 메타필드 키는 `custom.material`이 됩니다.

**Destination Store**에서도 이 단계를 반복합니다(키와 유형이 동일해야 합니다).

<figure><img src="/media/e68676d721f26cb93ef7.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

#### **2단계: 상품에 메타필드 데이터 추가**

**Source Store**에서 상품으로 이동하여 **Metafields**까지 아래로 스크롤한 다음  > **Material** 아래에 `Cotton`을 입력합니다.

이제 이 상품에는 메타필드 `custom.material = "Cotton"`이 설정되었습니다.

<figure><img src="/media/97a6ddb98ed50e435682.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

#### **3단계: Tipo 앱에서 동기화 구성**&#x20;

* **Destination Store**에서 앱을 열고 > Connect Configuration **> Metafield Sync**로 이동합니다.
* **Specific Metafields**를 선택한 다음 > 메타필드 키 `custom.material`을 정확히 입력합니다.&#x20;

<figure><img src="/media/7a7d4dfafe848ed0a876.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

**결과**

* 앱이 Source Store에서 `custom.material`을 찾습니다.
* Destination 상품에 **없으면** 앱이 **생성합니다**.\
  \=>   결과: 두 스토어 모두 `custom.material = "Cotton"`
* Destination에는 있지만 Source가 비어 있는 경우, 값을 **덮어쓰지 않습니다**.

***

### ❓FAQ

#### Q1: 스토어에서 `namespace.key`는 어떻게 설정하나요?

특정 메타필드를 동기화하려면 **메타필드 정의 키**를 `namespace.key` 형식으로 입력해야 합니다(예: `custom.color`).

Shopify 관리자에서 확인하는 방법은 다음과 같습니다.

1. Shopify Admin으로 이동하여 >**Settings > Custom Data > Products**로 이동합니다.
2. 동기화하려는 메타필드를 클릭합니다.\
   → **Namespace**와 **Key** 값이 표시됩니다.
3. 두 값을 `namespace.key` 형식으로 조합합니다.\
   → 예: `custom.description`

#### Q2: 메타필드가 동기화되지 않는 이유는 무엇인가요?

메타필드가 올바르게 동기화되지 않는다면 다음 중 하나가 원인일 수 있습니다.

1. **메타필드 동기화가 활성화되지 않음**\
   두 스토어 모두에서 메타필드 동기화가 켜져 있는지 확인하세요.
   * **Source Store**에서 **Share Metafields**를 활성화합니다.
   * **Destination Store**에서 **Receive Metafields**를 활성화합니다.

<figure><img src="/media/4360c99527c6a4de655c.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

2. **메타필드 정의 키가 추가되지 않음**

메타필드 동기화를 활성화하는 것 외에도 동기화하려는 **메타필드 정의 키(namespace.key)**를 추가해야 합니다.

* **Settings → Share Metafields**로 이동합니다.
* **Enable**이 선택되어 있는지 확인합니다.
* **Allow data**에서 다음 형식으로 메타필드 정의를 추가합니다.\
  `namespace.key`\
  예: `custom.material`&#x20;

<figure><img src="/media/f4d2b012b6b982aa41e6.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

3. **지원되지 않는 메타필드 유형**\
   **Reference types** 또는 **MetaObjects**와 같이 일부 메타필드 데이터 유형은 지원되지 않습니다.

빨간색: 앱에서 동기화할 수 없는 지원되지 않는 메타필드

<figure><img src="/media/85f75cd1117f373c78df.webp" alt="" loading="lazy" decoding="async"><figcaption></figcaption></figure>

4. **스토어 간 메타필드 유형 불일치**\
   Source와 Destination의 메타필드는 **데이터 유형과 구조가 동일**해야 합니다.\
   흔한 불일치 사례는 다음과 같습니다.

* 한쪽 메타필드는 **Single line text**이고 다른 쪽은 **Multi-line text**입니다.
* 한쪽 메타필드는 **Single value**를 사용하고 다른 쪽은 **List of values**를 사용합니다.

이러한 문제를 해결하려면 두 스토어의 메타필드가 동일한 **namespace**, **key**, **data type**을 가지고 있는지 확인한 다음 다시 동기화해 보세요.

***

**🙋 아직 도움이 필요하신가요?**

여전히 도움이 필요하시면 언제든지 <hi@tipo.io>로 문의해 주세요. 기꺼이 도와드리겠습니다.
