콘텐츠로 이동
앱 설치
한국어

이벤트

앱이 스토어에서 발생시키는 다섯 가지 이벤트와 각각의 실제 예시입니다.

앱은 이 이벤트를 document에서 발생시키므로 document.addEventListener로 수신하세요. 코드는 테마 에셋이나 theme.liquid의 </body> 위에 넣으세요.

이벤트detail발생 시점
gpoRenderCompleted{ form, product }옵션 렌더링이 완료되었을 때
gpoElementChanged{}고객이 옵션을 변경했을 때
gpoProductPriceUpdated{}표시된 가격이 다시 계산되었을 때
gpoValidated{ success }카트에 추가 시 검증이 실행되었을 때
gpoAddedToCart{}상품과 추가 옵션이 카트에 들어갔을 때

gpoRenderCompleted

옵션 필드가 DOM에 생성되면 발생합니다. 이 이벤트를 기반으로 코드를 작성하세요. 앱은 비동기로 렌더링하므로, DOMContentLoaded에서 실행되는 코드는 옵션이 생기기 전에 실행되어 아무것도 찾지 못합니다.

detail에는 옵션이 렌더링된 제품 양식인 form과 옵션이 렌더링된 대상 제품인 product가 담겨 있습니다.

document.addEventListener('gpoRenderCompleted', function (event) {
const { form, product } = event.detail;
if (!form) return; // 이 제품에 적용되는 옵션 세트가 없음
// 이제 옵션 필드를 안전하게 조회할 수 있음
form.querySelectorAll('.gpo-form__group').forEach(function (group) {
group.classList.add('my-theme-option');
});
});

옵션이 다시 렌더링될 때마다 다시 발생합니다. 제품을 다시 렌더링하는 테마에서 이형 상품이 바뀐 후나 GPOConfigs.initialize()를 호출한 후가 그렇습니다. 두 번 실행되어도 문제가 없도록 핸들러를 작성하세요.

gpoElementChanged

고객이 옵션을 변경할 때마다 발생합니다. 필드에 입력하거나, 스와치를 고르거나, 체크박스를 선택할 때입니다.

document.addEventListener('gpoElementChanged', function () {
const engraving = document.querySelector('[name="properties[Engraving text]"]');
const note = document.querySelector('.my-engraving-note');
if (!engraving || !note) return;
note.hidden = engraving.value.trim() === '';
});

텍스트 필드에서는 키를 누를 때마다 발생하므로, 네트워크 요청이나 무거운 레이아웃 재계산처럼 비용이 큰 작업은 디바운스하세요.

gpoProductPriceUpdated

고객이 선택한 옵션을 포함하도록 앱이 표시 가격을 다시 쓴 후 발생합니다. 고정 바, 요약 블록, 할부 예상 금액 등 자체 가격 표시를 동기화하는 데 사용하세요.

document.addEventListener('gpoProductPriceUpdated', function () {
const main = document.querySelector('[data-gpo-product-unit-price]');
const sticky = document.querySelector('.my-sticky-bar .price');
if (main && sticky) sticky.textContent = main.textContent;
});

페이지에 표시되는 가격은 미리 보기입니다. 고객에게 실제로 청구되는 금액은 결제 시 Shopify가 적용하므로, 이 금액을 최종 금액으로 취급하지 마세요. 가격이 적용되는 방식을 참조하세요.

gpoValidated

고객이 카트에 추가하려고 할 때 앱이 옵션을 확인한 후 발생합니다. 필수 옵션이 비어 있거나, 글자 수 제한을 넘었거나, 선택 수가 너무 적은 등 문제가 있으면 detail.success가 false입니다.

document.addEventListener('gpoValidated', function (event) {
if (event.detail.success) return;
// 카트에 추가가 차단됨
if (window.analytics) {
window.analytics.track('Option validation failed', {
product: window.GPOConfigs?.product?.handle
});
}
});

첫 번째 오류 메시지로 자동 스크롤이 켜져 있으면 앱이 이미 첫 번째 오류로 스크롤하므로 직접 처리할 필요가 없습니다. 위젯 동작을 참조하세요.

gpoAddedToCart

상품과 추가 옵션 제품이 모두 추가된 후 발생합니다. 이 시점에 카트가 실제로 변경되므로, 카트 열기와 분석 코드를 넣기에 알맞은 곳입니다.

document.addEventListener('gpoAddedToCart', function () {
fetch(window.Shopify.routes.root + 'cart.js')
.then(function (res) { return res.json(); })
.then(function (cart) {
document.querySelector('.my-cart-count').textContent = cart.item_count;
});
});

제품에 연결된 추가 옵션은 별도의 카트 품목이므로, 한 번의 카트에 추가로 여러 품목이 추가될 수 있습니다. 상품 하나가 추가되었다고 가정하지 말고 카트를 다시 읽으세요. 기본 제품과 추가 옵션 병합을 참조하세요.

참고

  • 다섯 가지 모두 앱 임베드가 활성화되어 있어야 합니다. 앱 임베드가 없으면 앱이 실행되지 않으며 아무 이벤트도 발생하지 않습니다.
  • 이벤트에는 페이지에 이미 있는 것 외의 고객 데이터가 담겨 있지 않습니다. 제품, 카트, 고객 정보는 window.GPOConfigs에서 읽으세요.
  • 여기에 연결하는 코드는 직접 유지 관리해야 하며, 테마나 앱 업데이트 후 스토어가 제대로 동작하지 않을 때 가장 먼저 확인해야 할 부분입니다.

도움이 되었나요?

문제 신고