Skip to main content
카탈로그는 상품, 매장, 콘텐츠처럼 여러 메시지에서 반복해서 사용하는 참조 데이터를 프로젝트에 저장하는 기능입니다. 유저 속성에 같은 정보를 복제하거나 메시지를 만들 때마다 외부 API를 호출하지 않고, 아이템 ID로 필요한 값을 조회해 메시지에 넣을 수 있습니다. 유저 데이터가 이름, 등급, 최근 구매일처럼 특정 유저에게 속한 정보라면, 카탈로그 데이터는 상품명, 가격, 이미지 URL처럼 여러 유저가 함께 참조하는 정보입니다. 이벤트에는 상품 ID만 기록하고 세부 정보는 카탈로그에서 관리하면, 메시지를 보낼 때 가장 최근에 반영된 값을 사용할 수 있습니다.
콘솔의 카탈로그 메뉴는 Pro Plan 이상을 이용하는 프로덕트에만 제공됩니다.

데이터 소스 선택하기

카탈로그를 만들 때 데이터 관리 방식에 맞는 소스를 선택합니다.
  • Google 스프레드시트: 운영자가 시트에서 데이터를 관리하고, 노티플라이가 전체 범위를 정해진 일정에 맞춰 동기화합니다. 모든 필드는 문자열로 저장됩니다.
  • API: 서버에서 Catalog REST API로 스키마와 아이템을 직접 관리합니다. string, number, boolean, time, geo, object, array 타입을 사용할 수 있습니다.
카탈로그에는 상품 정보처럼 개인을 식별하지 않는 참조 데이터만 저장하세요. 이름, 이메일, 전화번호, 외부 유저 ID, 프로필 값 등 개인정보를 Google 스프레드시트나 API 아이템에 포함하지 마세요. 노티플라이는 소스 값을 자동으로 분류하거나 가리지 않습니다. API로 카탈로그를 만들 때는 data_classificationnon_personal로 선언해야 합니다.

Google 스프레드시트 연결하기

1. 시트 준비하기

첫 번째로 값이 있는 행을 헤더로 사용합니다.
다음 규칙을 지켜 주세요.
  • 첫 번째 열 이름은 반드시 id여야 합니다.
  • 헤더는 비어 있거나 중복될 수 없으며 최대 250자입니다.
  • id와 헤더 이름은 영문 대소문자, 숫자, 하이픈(-), 밑줄(_)만 사용할 수 있습니다.
  • 아이템의 id는 최대 250자이며 카탈로그 안에서 고유해야 합니다. 상품 정보가 바뀌어도 유지되는 내부 식별자를 사용하는 것이 좋습니다.
  • 데이터가 있는 행에서 id가 비어 있거나 중복되면 동기화에 실패합니다.
  • 완전히 빈 행은 건너뜁니다. 헤더보다 값이 많은 행은 동기화 오류로 처리합니다.
  • Google 스프레드시트에 표시되는 값이 문자열로 저장됩니다. 가격과 날짜의 표시 형식을 먼저 확인하고, 숫자 비교나 배열 필드가 필요하면 API 카탈로그를 사용하세요.

2. 카탈로그 만들기

  1. 콘솔에서 데이터 > 카탈로그를 엽니다.
  2. 카탈로그 만들기를 누르고 데이터 소스로 Google Sheets를 선택합니다.
  3. 카탈로그 이름을 입력합니다. 프로젝트 안에서 고유한 이름을 사용하고, 메시지의 Liquid에서 그대로 참조할 수 있도록 products처럼 짧고 의미가 분명한 이름을 권장합니다. 이름은 250자 이하의 영문·숫자·한글·하이픈·밑줄을 사용할 수 있습니다.
  4. 스프레드시트 ID를 입력합니다. 특정 탭이나 범위만 가져오려면 시트 탭 이름 또는 A1 범위를 입력합니다. 둘 다 입력할 때는 같은 탭을 가리켜야 합니다. 둘 다 비우면 첫 번째 탭 전체를 읽습니다.
  5. Google Sheets의 공유 메뉴에서 catalog-reader@notifly.tech뷰어 권한을 부여합니다. 편집 권한은 필요하지 않습니다.
  6. 동기화 일정과 기준 시간대를 선택한 뒤 카탈로그를 만듭니다. 생성하면 첫 동기화가 바로 시작됩니다.
Google Sheets 카탈로그 생성 화면
스프레드시트 ID는 URL의 /d//edit 사이 값입니다.
예를 들어 https://docs.google.com/spreadsheets/d/1AbCdEfGhIjKlMnOpQrStUvWxYz/edit의 스프레드시트 ID는 1AbCdEfGhIjKlMnOpQrStUvWxYz입니다. A1 범위는 A1:Z50000 또는 Products!A1:Z50000처럼 입력합니다.

3. 동기화 일정 정하기

반복하지 않거나, 15분·30분 간격, 매시간, 매일, 매주, 매월 중 하나를 선택할 수 있습니다. 일정은 선택한 시간대의 시각을 기준으로 실행됩니다. 시각의 분은 00·15·30·45 중에서 선택하며, 매월 일정은 1일부터 28일까지 지원합니다.
  • 생성 직후 첫 동기화 및 지금 동기화는 정기 일정에 영향을 미치지 않습니다.
  • 데이터 소스를 수정하면 상태가 동기화 대기로 바뀝니다. 다음 정기 동기화 또는 지금 동기화 후 새 설정이 적용됩니다.
  • 변경된 내용이 없으면 동기화 기록은 변경 없음으로 남습니다.
  • 동기화가 실패하면 마지막으로 성공한 버전을 계속 사용합니다. 권한, 헤더, 행 형식을 수정한 뒤 다시 동기화하세요.
  • 비활성화한 카탈로그는 자동·수동 동기화와 메시지 조회에서 제외됩니다.

4. 결과 확인하고 정리하기

동기화가 끝나면 카탈로그 상세에서 다음 순서로 확인합니다.
  1. 상태와 활성 행 수를 확인합니다.
  2. 내용 미리보기에서 ID와 주요 필드가 원본 시트와 같은지 페이지별로 확인합니다.
  3. 동기화 기록에서 실행 방식, 시작·완료 시각, 행 수, 크기, 성공·변경 없음·실패 상태를 확인합니다.
  4. 실패했다면 공유 권한, 첫 번째 id 열, 빈·중복 헤더, 잘못된 행을 확인하고 고친 뒤 지금 동기화를 다시 실행합니다.
Google Sheets 카탈로그 상세와 동기화 기록
최근 동기화가 실패해도 이전에 성공한 버전이 있으면 그 데이터를 계속 메시지 개인화에 사용합니다.

5. 연결 정보와 이름 수정하기

카탈로그 상세 화면에서 수정을 누르면 이름, 스프레드시트 ID, 시트 탭, A1 범위, 동기화 일정을 바꿀 수 있습니다.
  • 데이터 원본이나 범위를 바꿨다면 저장한 뒤 동기화 결과를 다시 확인하세요.
  • 카탈로그 이름을 바꾸면 기존 캠페인과 유저 여정의 catalog_items·catalog_selection_items 태그도 새 이름으로 수정해야 합니다.
  • 데이터소스의 행이나 값을 바꿔도 캠페인과 유저 여정이 자동으로 시작되지는 않습니다. 카탈로그를 이용한 유저 여정 혹은 캠페인을 세팅해야 합니다.

6. 비활성화하거나 삭제하기

Google 스프레드시트 카탈로그의 비활성화영구 삭제는 다릅니다.
  • 비활성화: Liquid 조회와 자동·수동 동기화를 중지하지만 카탈로그 데이터와 동기화 기록은 유지합니다. 비활성화 후 콘솔에서는 영구 삭제만 진행할 수 있으므로 먼저 참조 중인 메시지가 없는지 확인하세요.
  • 영구 삭제: 아이템과 동기화 기록을 데이터베이스에서 삭제하며 복구할 수 없습니다.

API 카탈로그 만들기

API 카탈로그는 콘솔에서 데이터 소스로 API를 선택해 id:string 필드만 있는 빈 카탈로그를 만든 뒤 REST API로 필드와 아이템을 등록하거나, REST API로 스키마까지 한 번에 만들 수 있습니다. API로 만들 때는 API 인증 토큰을 발급받고 다음 요청을 보냅니다.
첫 번째 필드는 항상 { "name": "id", "type": "string" }이어야 합니다. 카탈로그를 만든 뒤 아이템은 한 번에 최대 50개씩 등록할 수 있습니다.
REST API로는 API 소스이면서 활성 상태인 카탈로그만 조회·변경할 수 있습니다. Google 스프레드시트 카탈로그는 콘솔에서 관리하세요. API 카탈로그의 콘솔 화면은 생성·목록·상세·아이템 미리보기와 REST 사용 예시를 제공합니다. 아이템·필드·셀렉션 변경과 카탈로그 영구 삭제는 REST API에서 수행해야 하며, 콘솔에서는 수정·동기화·비활성화·삭제할 수 없습니다.

메시지에서 아이템 사용하기

메시지 에디터에서 catalog_items 태그에 카탈로그 이름과 아이템 ID를 차례로 전달합니다. 조회 결과는 items 배열에 저장됩니다.
지원 범위예약·이벤트 기반 캠페인과 유저 여정에서는 앱/웹 푸시, 문자, 카카오 알림톡, 카카오 브랜드메시지, 웹훅에서 사용할 수 있습니다.채널과 관계없이 API 기반 발송 캠페인은 지원하지 않습니다. 이 경로에서는 카탈로그를 조회하지 않아 items가 빈 배열로 처리됩니다. API 직접 발송도 카탈로그를 조회하지 않으므로, 호출하기 전에 필요한 값을 직접 조회해 메시지에 넣어야 합니다.

이벤트 기반 캠페인

이벤트 파라미터에 상품 ID가 들어 있다면 event에서 읽을 수 있습니다.
이벤트 기반 캠페인에서는 event를 사용합니다.

유저 여정

이벤트로 시작한 유저 여정에서는 진입 이벤트의 파라미터를 entry_event에서 읽습니다.

여러 항목 조회하기

여러 ID를 공백으로 구분하면 한 번에 조회할 수 있습니다. 유저 속성이나 이벤트 파라미터도 ID 자리에 넣을 수 있습니다.
존재하는 아이템은 요청한 ID 순서대로 저장됩니다. 찾지 못한 ID는 결과에서 빠져 뒤 아이템의 배열 번호가 앞당겨질 수 있고, 같은 ID를 여러 번 요청하면 한 번만 들어갑니다. 항상 items.size를 확인하거나 for로 순회한 뒤 값을 사용하세요. 조회 결과가 비어 있으면 대체 문구를 보여주거나, 채널에서 지원하는 경우 abort_message로 발송을 중단할 수 있습니다. 같은 메시지에서 카탈로그 태그를 다시 호출하면 items 배열이 새 결과로 바뀝니다. 카탈로그 필드 안에 Liquid 문법이 들어 있고 그 값까지 다시 렌더링해야 한다면 :rerender 옵션을 사용합니다.
재귀적인 카탈로그 호출은 허용되지 않습니다. 신뢰할 수 있는 템플릿 값에만 :rerender를 사용하세요.

셀렉션 사용하기

API 카탈로그에서는 필터·정렬·개수 조건으로 셀렉션을 만들 수 있습니다. 셀렉션은 최대 30개, 셀렉션마다 필터는 최대 4개, 결과는 최대 50개입니다. 필드 타입별로 사용할 수 있는 연산자가 정해져 있습니다. stringequals·does not equal, number는 두 연산자와 greater than·less than, booleanis, timebefore·after, arrayincludes value·does not include value를 지원합니다. geoobject는 필터링할 수 없고 필터 값에 null을 사용할 수 없습니다.
메시지에서는 다음처럼 조회합니다.
아이템이나 필드를 수정하면 저장된 셀렉션 결과도 함께 다시 계산됩니다. 셀렉션에서 사용 중인 필드는 먼저 셀렉션을 삭제하기 전까지 삭제할 수 없습니다.

문제 해결

공유 설정에서 catalog-reader@notifly.tech에 뷰어 권한이 있는지 확인하세요. 스프레드시트 ID와 시트 탭 이름도 함께 확인합니다.
첫 번째 열 이름이 소문자 id인지, 헤더가 비어 있거나 중복되지 않았는지 확인하세요. 각 행의 id와 헤더에는 영문·숫자·하이픈·밑줄만 사용할 수 있으며, 데이터 행의 열 수가 헤더보다 많아도 동기화에 실패합니다.
시트를 수정해도 메시지 값이 즉시 바뀌지는 않습니다. 다음 정기 동기화를 기다리거나 지금 동기화를 실행한 뒤, 상세 화면의 최근 동기화 시각과 내용 미리보기를 확인하세요.
카탈로그 값이 바뀌어도 발송은 시작되지 않습니다. 재입고나 가격 인하 이벤트를 노티플라이로 보내고, 해당 이벤트를 캠페인 또는 유저 여정의 시작 조건으로 설정하세요. 카탈로그에서는 메시지에 표시할 상품명, 가격, 링크 등을 조회합니다.

주요 제한

  • 프로젝트당 활성 카탈로그: 최대 20개
  • Google 스프레드시트 카탈로그 필드: id 제외 최대 1,000개
  • API 카탈로그 필드: id 포함 최대 500개
  • 필드 추가 요청: 한 번에 최대 50개
  • 아이템 생성·수정·삭제 요청: 한 번에 최대 50개
  • 아이템 한 개의 저장 크기: 최대 1 MiB
  • 카탈로그 한 개의 저장 크기: 최대 2 GiB
  • 프로젝트의 활성 카탈로그 합계: 최대 15 GiB
  • 카탈로그·필드·아이템 ID: 최대 250자
  • 문자열: 최대 5,000자
  • 배열: 문자열 최대 100개
  • object·array 중첩: 최대 50단계, object key에는 . 또는 $ 사용 불가
  • Google 스프레드시트 동기화 소스: 1회 최대 100 MiB
  • API JSON 요청 본문: 최대 4 MiB
API의 전체 경로, 요청·응답 스키마, 상태 코드는 Catalog REST API 시작하기API Reference > 카탈로그에서 확인할 수 있습니다. Braze에서 옮기는 경우 Braze Catalog에서 마이그레이션하기를 참고하세요.