Konfigurasi Meta Marketing API

Modul Meta Marketing API di Sinema memungkinkan pengiklan menghubungkan akun Facebook/Meta Ads secara langsung melalui System User Access Token. Integrasi ini memungkinkan penarikan data biaya iklan (Ad Spend) secara real-time sehingga kalkulasi ROAS, Laba Bersih (Net Profit), dan ROI di Command Center terhitung secara otomatis dan presisi.

flowchart LR
    MBM["Meta Business Manager\n(System User Token)"] -->|"Graph API\n(ads_read & insights)"| Sinema["Sinema Plugin\n(Command Center)"]
    Shopee["Komisi Affiliasi / CSV"] --> Sinema
    Sinema -->|"Kalkulasi Otomatis"| ROI["Metrik Finansial:\n• Total Ad Spend\n• Estimasi ROAS\n• Net Profit"]

---

1. Persiapan di Meta Business Manager

Sebelum mengisi formulir konfigurasi di plugin Sinema, Anda perlu membuat Permanent System User Access Token melalui Meta Business Settings (Pengaturan Bisnis):

┌──────────────────────────────────────────────────────────┐
│ LANGKAH PEMBUATAN TOKEN DI META BUSINESS MANAGER         │
├──────────────────────────────────────────────────────────┤
│ 1. Buat Pengguna Sistem (System User) bertipe Admin      │
│ 2. Tetapkan Aset (Assign Assets): Akun Iklan & Aplikasi   │
│ 3. Hasilkan Token Baru dengan 3 Izin Wajib:              │
│    • ads_read                                            │
│    • ads_management                                      │
│    • read_insights                                       │
└──────────────────────────────────────────────────────────┘

Langkah-langkah detail:

1. Buat Pengguna Sistem (System User):

   • Masuk ke Pengaturan Bisnis > Pengguna > Pengguna Sistem (Users > System Users).
   • Klik Tambah (Add), beri nama pengguna (misal: Sinema-Sync-Bot), dan pilih peran sebagai Admin Sistem.

2. Hubungkan Aset Akun Iklan (Assign Assets):

   • Pilih Pengguna Sistem yang baru dibuat, lalu klik tombol Tetapkan Aset (Add Assets).
   • Pilih Akun Iklan (Ad Accounts), pilih akun iklan yang ingin dipantau, lalu aktifkan opsi Kelola Akun Iklan (Full Control / Admin).
   • Jika Anda memiliki Meta App, hubungkan juga aset Aplikasi (Apps).

3. Hasilkan Token Permanen (Generate Token):

   • Klik Buat Token Baru (Generate New Token).
   • Pilih aplikasi Meta Anda dan atur masa berlaku token (Token Expiration) ke Never / Permanen.
   • Pada daftar izin (Scopes), centang 3 izin wajib:
     • ads_read — Membaca data kampanye dan ad set.
     • ads_management — Mengambil struktur penempatan dan status iklan.
     • read_insights — Menarik metrik performa dan biaya iklan (Ad Spend).
   • Klik Buat Token, lalu salin string token panjang yang muncul (diawali dengan EAAB...).

Simpan Token dengan Aman

Meta hanya menampilkan token permanen ini satu kali saat dibuat. Simpan string token ini di catatan rahasia atau pengelola kata sandi Anda sebelum menutup jendela popup.

---

2. Mengisi Konfigurasi di Sinema

Setelah mendapatkan token dan ID akun iklan, masukkan data tersebut ke dalam plugin Sinema:

1. Masuk ke dasbor admin WordPress Anda, buka menu Sinema > Command Center (atau Sinema > ROI Dashboard).
2. Pada toolbar atas, klik ikon roda gigi ⚙ (Pengaturan Meta Marketing API) di sebelah tombol Sync Meta Spend.
3. Lengkapi formulir modal konfigurasi:

┌──────────────────────────────────────────────────────────────────┐
│ MODAL PENGATURAN META MARKETING API                              │
├──────────────────────────────────────────────────────────────────┤
│ Meta Permanent Access Token *                                    │
│ [ EAABsb7...                                              ] [👁] │
│ Izin: [ads_read] [ads_management] [read_insights]                │
├──────────────────────────────────────────────────────────────────┤
│ Facebook Ad Account IDs *                                        │
│ [ 123456789012345                                              ] │
│ [ 987654321098765                                              ] │
│ Format: 1 ID per baris atau pisahkan dengan koma                 │
├──────────────────────────────────────────────────────────────────┤
│ Meta App ID (Opsional)      │ Meta App Secret (Opsional)        │
│ [ 123456789012345         ] │ [ ••••••••••••••••••••••    ] [👁] │
├──────────────────────────────────────────────────────────────────┤
│ [ 🔌 Test Connection ]                [ Batal ] [ 💾 Simpan ]   │
└──────────────────────────────────────────────────────────────────┘

Parameter Konfigurasi:

Parameter	Wajib / Opsional	Deskripsi
Meta Permanent Access Token	Wajib	Token akses panjang EAAB... milik System User dengan izin ads_read, ads_management, dan read_insights.
Facebook Ad Account IDs	Wajib	Satu atau beberapa ID Akun Iklan Facebook yang ingin dipantau. Mendukung multi-akun (pisahkan dengan koma atau baris baru).
Meta App ID	Opsional	ID Aplikasi dari dasbor Meta for Developers (Menu Settings > Basic).
Meta App Secret	Opsional	Kunci rahasia aplikasi dari dasbor Meta for Developers untuk keperluan integrasi mendalam.

Format ID Akun Iklan

Sistem mendukung penulisan ID dalam format 123456789, act=123456789, atau act_123456789. Sinema secara otomatis menstandarkan format ID saat melakukan request ke Graph API.

---

3. Uji Koneksi & Sinkronisasi Biaya Iklan

1. Uji Koneksi (Test Connection):

   • Klik tombol Test Connection di dalam modal.
   • Sinema akan melakukan panggilan validasi ke endpoint Meta Graph API.
   • Jika berhasil, akan muncul notifikasi hijau berlabel Koneksi Meta API Berhasil!.

2. Simpan Pengaturan:

   • Klik tombol Simpan Konfigurasi. Status badge akan berubah menjadi 🟢 Token Terpasang.

3. Sinkronkan Data Biaya Iklan:

   • Di toolbar Command Center, klik tombol Sync Meta Spend.
   • Indikator loading akan berputar dan menarik total biaya iklan untuk periode tanggal yang dipilih.
   • Metrik pada KPI Bar Finansial (Total Ad Spend, Estimasi ROAS, Net Profit) akan diperbarui secara instan.

---

4. Troubleshooting & Keamanan

Kendala Umum (Troubleshooting):

• Error: Invalid OAuth access token: Token telah kedaluwarsa, dihapus di Business Manager, atau salah salin. Hasilkan token permanen baru di menu System Users.
• Error: Permissions error / (#273) This Ads API call requires user to be admin: Pastikan System User telah ditambahkan sebagai pengelola aset (Assign Assets) pada akun iklan bersangkutan dengan level izin admin/full control.
• Biaya Iklan Bernilai 0: Periksa apakah ID Akun Iklan yang dimasukkan sesuai dengan akun tempat kampanye aktif berjalan, dan pastikan filter tanggal di Command Center mencakup periode penayangan iklan.

Keamanan Token & Kredensial

Jangan pernah membagikan Access Token atau App Secret kepada pihak yang tidak berwenang, jangan memasukkannya ke dalam repositori publik (git repository), atau mengirimkannya melalui tangkapan layar publik.