Mengatur Sumber Data dan Cache Notifikasi Penjualan (LarisTurbo)

Cara kerja cache Sales Notification LarisTurbo: order mana yang dipakai, file wcsales.json, tombol Refresh / Update, dan solusi jika data notifikasi tidak terbarui.

Tutorial ini melengkapi Cara Mengatur Sales Notification di WooCommerce dengan fokus ke sumber data dan cache di balik popup. Bagian ini jarang disentuh saat setup normal, tapi penting saat troubleshooting: popup tidak muncul, data terasa ketinggalan, atau Anda ingin memastikan notifikasi benar-benar berasal dari order asli.

Prinsip dasar

Sales Notification For WooCommerce tidak menghubungi layanan eksternal untuk mengambil “notifikasi palsu”. Semua teks dan gambar produk di popup berasal dari:

Query order WooCommerce di database situs Anda
File cache JSON di server
Script frontend yang membaca file tersebut dan menampilkan popup bergantian

Memahami alur ini membantu Anda membedakan masalah pengaturan, data order, atau cache file.

Order mana yang masuk ke notifikasi?

Saat cache dibangun ulang, plugin mengambil maksimal 10 order terbaru (orderby: date, order: DESC).

Status order yang diabaikan

Order dengan status berikut tidak dipakai:

Refunded
Failed
Cancelled
Checkout draft

Order dengan status lain yang terdaftar di WooCommerce (misalnya Processing, Completed, On hold) ikut dipertimbangkan selama masih masuk 10 order terbaru.

Data per line item produk

Satu order bisa berisi banyak produk. Plugin membuat satu entri notifikasi per produk dalam order, bukan satu entri per order saja.

Contoh: order dengan 2 produk berbeda bisa memunculkan 2 popup bergantian, keduanya memakai nama pelanggan dan kota yang sama tetapi nama produk berbeda.

Field order yang dipakai

Data popup	Sumber di order
Nama pelanggan	`billing_first_name` + `billing_last_name`
Kota	`billing_city` (plugin membersihkan format seperti `Kota Jakarta` → `Jakarta`)
Negara	`billing_country` (dinormalisasi ke nama negara)
Nama produk	Nama produk di line item
Gambar produk	Featured image produk, atau gambar placeholder WooCommerce jika kosong
Link produk	URL halaman produk
Waktu	Tanggal dibuat order (`date created`)

Jika produk sudah dihapus dari katalog tetapi masih ada di order lama, line item itu bisa dilewati dan tidak muncul di notifikasi.

File cache: `wcsales.json`

Setelah data order dikumpulkan, plugin menyimpan JSON ke:

wp-content/uploads/laristurbo/wcsales.json

URL publik file mengikuti wp-content/uploads/laristurbo/wcsales.json (dipakai script frontend).

Kapan file dibangun ulang?

Pemicu	Perilaku
Halaman frontend pertama kali dimuat setelah fitur aktif	File dibuat jika belum ada
Order baru dibuat (`woocommerce_new_order`)	Plugin menandai cache perlu update; file diperbarui saat halaman frontend berikutnya dimuat
Order di-trash	Sama: ditandai perlu update
Klik Refresh / Update di Cached Data	File langsung dibangun ulang paksa
File sudah ada dan tidak ada pemicu update	Plugin memakai cache lama (tidak query order setiap request)

Tombol Refresh / Update berguna saat development atau setelah impor order, tanpa menunggu kunjungan pengunjung berikutnya.

Syarat server

Folder wp-content/uploads/laristurbo/ harus bisa dibuat dan ditulis PHP. Jika permission salah, popup tidak punya data untuk dibaca meskipun Enable Sales Notification aktif.

Tombol Refresh / Update

Langkah manual:

Buka LarisTurbo → For WooCommerce → Sales Notification For WooCommerce → Settings.
Scroll ke bagian Cached Data.
Klik Refresh / Update.
Tunggu redirect kembali ke halaman settings dengan pesan Sales notification data updated successfully.

Tombol ini aman dipakai berulang saat testing. Hanya user dengan kapabilitas manage_options yang bisa menjalankannya (admin situs).

Beberapa perilaku diatur di kode plugin, tidak ada field di Settings. Berguna saat Anda bertanya “kenapa popup hilang cepat?” tanpa mengira ada bug:

Perilaku	Nilai default
Jeda sebelum popup pertama	Sekitar 3 detik setelah halaman dimuat
Durasi tampil satu notifikasi	Sekitar 5 detik sebelum berganti
Offset dari tepi layar	Sekitar 12 px dari sudut yang dipilih

Nilai ini tidak bisa diubah dari UI standar; penyesuaian lanjutan hanya via kode/tema (filter developer).

WooCommerce HPOS

Jika Anda memakai High-Performance Order Storage (HPOS), query order tetap lewat API WooCommerce (wc_get_orders). Sales Notification tidak memerlukan pengaturan khusus HPOS, asalkan order tampil normal di WooCommerce → Orders.

Skenario umum

Baru install, belum pernah ada order

Popup tidak akan menampilkan apa pun karena wcsales.json kosong atau tidak terbentuk dengan data. Buat order uji (bisa COD atau payment gateway test), lalu klik Refresh / Update.

Klik Refresh / Update, buka tab incognito, reload halaman shop. Cache tidak selalu real-time di admin; pembaruan mengikuti aturan di tabel pemicu di atas.

Ingin “menyembunyikan” notifikasi sementara tanpa uninstall

Hapus centang Enable Sales Notification dan simpan. File cache bisa tetap ada di server tetapi tidak dibaca frontend.

Privasi dan order asli

Karena data 100% dari order Anda, hindari order uji dengan nama pelanggan asli jika tidak ingin nama itu muncul di popup (terutama jika Hide Customer Name nonaktif). Untuk staging, pakai nama fiktif di field billing.

Troubleshooting lanjutan

File `wcsales.json` ada tapi isinya `[]`

10 order terbaru mungkin semua berstatus dikecualikan, atau tidak punya line item produk valid
Coba buat order Completed atau Processing dengan produk yang masih ada

Script dimuat lewat wp_footer. Tema yang tidak memanggil wp_footer() di template custom bisa menghambat fitur. Bandingkan dengan tema default WooCommerce.

Customizer / widgets.php

Plugin sengaja tidak menampilkan script saat referer dari widgets.php agar tidak mengganggu layar customizer.