Katalog Embed

Katalog embed memungkinkan katalog Commerce tampil di domain lain — misal blog, landing page klien, atau portal mitra. Pengunjung bisa menambahkan produk ke keranjang di situs tersebut, lalu keranjangnya disalin otomatis ke checkout di situs utama Anda.

Mengaktifkan

Di Advanced Settings → Embed:

1. Aktifkan Enable embeddable catalog handoff.
2. Isi Allowed Embed Origins — satu origin per baris (misal https://blog.example.com). Gunakan * hanya untuk testing.
3. Sesuaikan batas bila perlu: Max Handoff Lines (default 20 baris), Max Quantity Per Line (default 99), Handoff Token TTL Seconds (default 600 detik).

Memasang di Situs Eksternal

Settings menyediakan snippet siap salin; bentuknya seperti ini:

<script
  src="https://tokosaya.com/wp-content/plugins/sejoli-commerce/assets/embed/embed-catalog.js"
  data-catalog="main"
  data-target="#catalog"
  data-checkout-url="https://tokosaya.com/checkout">
</script>

• data-catalog — kunci katalog (main untuk katalog utama).
• data-target — selector elemen tempat katalog dirender.
• data-checkout-url — URL checkout situs utama.

Atribut opsional lain (snippet siap salin di settings sudah menyertakannya sesuai pengaturan Anda):

Tampilan Katalog

Toolbar dan kartu embed mengikuti tampilan katalog toko Anda:

• Kategori sebagai pill dengan badge jumlah produk — bukan dropdown.
• Toggle grid/list di kanan toolbar; pilihan pengunjung tersimpan di browser mereka.
• Tombol keranjang di toolbar hanya tampil pada pola per-halaman tanpa minicart (data-minicart="no"). Dengan script footer + minicart aktif, bubble melayang menjadi satu-satunya pintu keranjang — toolbar lebih bersih untuk pencarian dan filter.
• Modal detail menampilkan isi lengkap produk (konten editor) dan menyertakan tombol Bagikan (Facebook, WhatsApp, Salin Link). Link yang dibagikan menunjuk halaman embed dengan ?product={slug} — penerima membukanya dan modal produk yang sama langsung terbuka.
• Kartu produk mengikuti pengaturan Tampilan Tombol Tambah ke Keranjang: mode ikon menampilkan harga di kiri dan tombol keranjang di kanan kartu; mode teks menampilkan tombol Tambah Keranjang penuh. Menampilkan gambar atau judul membuka detail produk dalam modal — termasuk tag produk sebagai chip.

Alur Handoff

Prosesnya berjalan otomatis tanpa setup tambahan: pengunjung menekan Add to Cart di situs eksternal, dan saat menuju checkout keranjang dipindahkan ke situs utama lewat token sekali pakai yang kadaluarsa cepat dan hanya sah dari origin yang diizinkan — pengunjung melanjutkan checkout di situs utama sebagai guest atau akunnya sendiri.

Token handoff bersifat sekali pakai, kadaluarsa cepat (TTL), dan hanya sah dari origin yang diizinkan.

Events untuk Integrator

Script embed memancarkan event standar yang bisa dipakai tema/plugin Anda tanpa menyentuh kode embed:

API programatik sejoliCommerceEmbedCart.add(id, qty) / .count() tercakup di bagian tombol kustom di atas.

Referensi API

Embed berbicara ke REST API Commerce di namespace sejoli-commerce/v1:

Storefront Level Situs — Satu Script di Footer

Selain dipasang per-halaman (pola di atas), script yang sama bisa dipasang sekali di footer tema domain storefront. Dengan satu script itu:

• Minicart melayang tampil di pojok layar di semua halaman (desktop) dan menjadi drawer bottom-sheet di layar mobile — keranjangnya satu dan sama dengan katalog maupun buy-box, karena tersimpan di satu tempat di browser (localStorage per domain).
• Halaman memilih isi lewat container: grid katalog di homepage, buy-box satu produk di halaman salespage, atau tanpa keduanya (hanya minicart).
• Tombol Checkout di minicart memakai handoff token yang sama — keranjang dipindah ke checkout situs utama persis seperti alur di atas. Tidak ada pengaturan tambahan.

Memasang

Salin snippet dari Advanced Settings → Integrations → Site-Level Storefront Script, lalu tempel di footer tema storefront. Di kartu yang sama tersedia pilihan Posisi widget minicart (kanan-bawah default, kiri-bawah, kanan-atas, kiri-atas) — pilih dulu, snippet otomatis menyesuaikan:

<script
  src="https://tokosaya.com/wp-content/plugins/sejoli-commerce/assets/embed/embed-catalog.js"
  data-checkout-url="https://tokosaya.com/checkout"
  data-cart-bar="no"
  async>
</script>

Lalu di halaman yang diinginkan, tempel container-nya:

<!-- Homepage / halaman katalog: -->
<div data-sjc-catalog></div>

<!-- Salespage satu produk (ID terisi otomatis lewat picker di settings): -->
<div data-sjc-buybox data-product="123"></div>

Footer Script + Embed Per-Halaman di Situs yang Sama

Kedua pola boleh terpasang bersamaan — misal footer script untuk minicart sitewide, sementara halaman tertentu memakai snippet katalog per-halaman. Script ini aman terhadap situasi itu:

• Eksekusi pertama menjadi host: memegang seluruh layanan bersama (minicart, buy-box, tombol kustom, sinkronisasi, API). Eksekusi berikutnya tidak menambah bubble kedua atau listener ganda.
• Katalog hanya dirender sekali per container — container yang sudah terlayani ditandai dan dilewati script lain.
• Keranjang adalah milik bersama: perubahan dari permukaan mana pun langsung terlihat di minicart, katalog, dan buy-box (baca-ulang storage pada tiap perubahan).
• Konfigurasi layanan bersama (posisi minicart, data-minicart-mobile, dst.) mengikuti script yang terpasang lebih dulu — taruh snippet footer sebelum snippet per-halaman di HTML halaman bila keduanya ada.

Buy-box di Halaman Salespage

Buy-box merender kotak ringkas di halaman salespage: gambar opsional, nama, harga (termasuk harga promo), pilihan varian (pill untuk ≤6 opsi, dropdown bila lebih), jumlah, dan tombol tambah ke keranjang — tanpa pindah halaman.

Satu hal yang perlu diperiksa: buy-box mengambil data lewat endpoint detail yang buyer-safe — produk harus:

• berstatus publish dan bukan produk tertutup (closed),
• tampil di katalog Commerce (aktifkan visibilitas katalognya di pengaturan produk).

Picker produk di settings menandai produk yang belum tampil di katalog dengan label "di luar katalog".

Tombol Kustom (Page Builder / Landing Page)

Salespage hasil page builder (Elementor, Gutenberg, dll.) tidak harus memakai container buy-box — tombol apa pun bisa menjadi tombol tambah-ke-keranjang cukup dengan satu atribut:

<!-- Minimal: -->
<button data-sjc-add-to-cart="123">Beli Sekarang</button>

<!-- Lengkap: jumlah + label sesaat setelah ditambahkan: -->
<a href="#" data-sjc-add-to-cart="123" data-sjc-add-to-cart-qty="2"
   data-sjc-added-label="✓ Masuk keranjang">+ Keranjang</a>

<!-- Produk ber-varian: varian dipilih lewat atribut "kunciGrup=kunciOpsi"
     (pisah koma untuk lebih dari satu grup): -->
<button data-sjc-add-to-cart="456"
        data-sjc-variant="warna=warna:::crazy-horse-tan:::0"
        data-sjc-added-label="✓ Masuk keranjang">Beli</button>

Cara kerjanya: klik → detail produk diambil dari endpoint detail (sekali, lalu di-cache) → item masuk keranjang level situs yang sama dengan katalog/buy-box → badge minicart bertambah dan bubble berdenyut (berfungsi di semua tombol, tanpa atribut apa pun). Listener dipasang di level dokumen, jadi tombol hasil render dinamis page builder tetap berfungsi tanpa konfigurasi tambahan.

Catatan penting:

• Pakai atribut, bukan class — atribut data-sjc-* adalah kontrak resmi embed dan tidak akan bertabrakan dengan class tema/builder Anda.
• Produk ber-varian kini bisa lewat tombol kustom — sertakan data-sjc-variant dengan pasangan kunciGrup=kunciOpsi (lihat tabel di atas). Tanpa atribut varian untuk grup yang wajib, tombol menampilkan peringatan memilih varian alih-alih menambah item kurang-lengkap. Buy-box tetap jadi pilihan bila Anda ingin UI pemilihan varian yang lengkap (pill per opsi) langsung di halaman.
• Syarat produk sama dengan buy-box: publish, tidak tertutup, dan tampil di katalog Commerce.
• Berfungsi di domain tempat script embed terpasang. Untuk tombol di situs commerce itu sendiri gunakan shortcode native (sejoli_commerce_cart_button), bukan atribut ini.
• Integrasi programatik: sejoliCommerceEmbedCart.add(123, 2) (mengembalikan Promise) menerima argumen ketiga opsional untuk varian — { variants: ["warna:::crazy-horse-tan:::0"], labels: ["Warna: Crazy Horse Tan"], extra: 0 } — dan sejoliCommerceEmbedCart.count() membaca isi keranjang.

Atribut Kustomisasi Script

Default di atas sengaja dipilih agar tanpa diketik pun hasilnya sudah benar: minicart melayang di desktop dan drawer di mobile. Edit script hanya bila Anda berada di situasi pada kolom "Kapan perlu". Semua atribut ditulis di tag <script> footer (container punya atributnya sendiri, di bagian paling bawah).

Untuk container (bukan script): data-product="{id}" wajib di buy-box; data-show-image="no" menyembunyikan thumbnail buy-box; atribut katalog lain (data-columns-*, data-featured, dst.) tetap berlaku di container data-sjc-catalog.

Catatan Teknis (opsional dibaca)

• Satu keranjang per domain storefront — key localStorage sjc_embed_cart::{url-commerce}. Keranjang per-katalog dari pola lama dimigrasi otomatis saat halaman pertama dibuka dengan script baru.
• Baris keranjang dibedakan oleh produk + varian — sama dengan identitas baris di server, jadi tidak ada baris duplikat saat handoff.
• Antar permukaan (katalog, buy-box, minicart) saling sinkron lewat event sejoli-commerce:embed-cart-updated; antar tab browser lewat event storage bawaan browser.