Ghi chú SDK Integration Backend: window.appifio tự động nạp
Bootstrap SDK

DINHDANH Creator · Bài AM09 · SECTION CÁC BIẾN VÀ HÀM TOÀN CỤC

Bootstrap tự inject
biến & client sẵn sàng

Hệ thống chèn sẵn cấu hình và thư viện API trước HTML app của bạn. Bạn không tự load script client - chỉ cần biết đợi đúng cách rồi gọi appifio_client.

Mục tiêu: Hiểu window.appifio.global.apps, cách appifio_client luôn tồn tại, và pattern waitForAppStorage trước mọi lời gọi API.

Trước: AM01 · AM08 · Sau: AM10 (URL & dữ liệu rỗng)

Nguồn chuẩn: Hướng dẫn API Aura Storage · mục biến & hàm toàn cục

1. App Storage Bootstrap là gì?

Khi visitor mở trang app, platform inject một đoạn script nhỏ (App Storage Bootstrap) vào - chạy trước nội dung HTML trong sync_data/{url_name}/. Bootstrap:

  • Gán object cấu hình window.appifio.global.apps
  • Tạo getter appifio_client (proxy hoặc instance thật)
  • Tự nạp thư viện appifio_client bản Aura khi backend = Advanced
  • Định nghĩa các hàm helper toàn cục (waitForAppStorage, …)
Bạn không tự thêm thẻ <script src="https://dinhdanh.com/uploads/pages/appifio-am09-appifio-client-luon-san-sang.jpg"> và không tự tạo window.appifio - hệ thống đã làm sẵn.

2. window.appifio.global.apps - thông tin app

Object này cho biết app đang chạy ở đâu và endpoint API nào. Client tự đọc các giá trị này khi gửi request - bạn hiếm khi cần gửi tay.

FieldNghĩa đời thường
url_nameSlug app trên URL - mọi API gửi kèm tên này
api_urlĐịa chỉ endpoint Aura Storage (POST duy nhất)
site_urlGốc domain platform - dùng ghép link tuyệt đối (xem AM10)
api_keyToken phiên trang - client tự gửi kèm mỗi request (encoded_key); không phải mật khẩu admin
backend_version'advanced' → Aura client (loạt AM này); 'easy' → client đơn giản hơn
// Đọc khi cần (vd. build link, debug)
const urlName = window.appifio.global.apps.url_name
const siteUrl = window.appifio.global.apps.site_url.replace(/\/$/, '')
const apiUrl  = window.appifio.global.apps.api_url
Sau khi admin đăng nhập, client tự giữ phiên và tự gửi token quản trị kèm request - bạn không cần tự gắn vào từng lời gọi. Chi tiết auth: AM06.

3. Aura CMS - inject thêm (nếu bật)

Khi Aura CMS bật, bootstrap còn inject:

window.__AURA_CMS_DISPLAY_FORMATS__ = { date, time, datetime_display, timezone, ... }

Biến này giúp appifio_formatDateTime tự theo cài đặt CMS - không tự đọc cms-settings thủ công. Xem AM08 (helper formatDateTime).

4. appifio_client - luôn tồn tại

DINHDANH Creator Code: mã live dùng window.appifio trong JavaScript dự án
appifio_client sẵn sàng

Bootstrap dùng Object.defineProperty - getter trả về proxy hoặc instance thật:

Trạng tháiappifio_client trả về
Script client chưa load xongproxyClient - mọi appifio_*() được xếp hàng, tự chạy khi ready
AppStorageClient đã khởi tạoclientInstance thật
✅ Đúng
await window.waitForAppStorage()
const result = await appifio_client.appifio_readList('blog.json', ['id','title'])

// Gọi sớm cũng OK - proxy xếp hàng
const early = await appifio_client.appifio_readFile('contacts.json')
❌ Sai - đừng làm
  • typeof appifio_client === 'undefined' - getter luôn có, check này vô nghĩa
  • if (appifio_client.appifio_readFile) để biết “đã ready” - proxy luôn trả function giả → luôn truthy dù chưa load
  • Loop poll appifio_readFile để đợi - dùng waitForAppStorage() thay thế

DOMContentLoaded bị defer: nếu bạn đăng ký listener sau bootstrap, hệ thống vẫn giữ queue đến khi client ready và DOM ready - code trong listener an toàn gọi API.

5. Hàm helper toàn cục

HàmHành vi
waitForAppStorage()Promise - resolve khi client thật sẵn sàng (đã có → resolve ngay)
onAppStorageReady(cb)Gọi cb(client) - sync nếu đã ready, không thì sau load
withClient(async (client) => …)Load client rồi chạy callback với instance thật
getAppStorageClient() / getClient()Trả instance hoặc proxy (có thể vẫn là proxy)
initAppStorage()Alias của loadAppStorageClient() - hiếm cần gọi tay

Event:

window.addEventListener('appStorageClientReady', (e) => {
  const client = e.detail.client
  // client đã sẵn sàng
})

6. Pattern khuyến nghị - copy dùng được

// Pattern ngắn nhất - mọi trang HTML app
document.addEventListener('DOMContentLoaded', async () => {
  await window.waitForAppStorage()
  const list = await appifio_client.appifio_readList('blog.json', ['id', 'title', 'slug'])
  const rows = list.data?.content || []
  // render...
})

// Hoặc dùng callback
window.onAppStorageReady(async (client) => {
  await client.appifio_readList('contacts.json', ['id', 'name'])
})

Fallback (trang không có bootstrap - hiếm):

try {
  if (typeof window.waitForAppStorage === 'function') {
    await window.waitForAppStorage()
  } else {
    console.warn('AppStorage bootstrap missing - API unavailable')
  }
} catch (error) {
  console.warn('Error waiting for AppStorage:', error)
}

Checklist

  1. Mọi trang có JS API đều await waitForAppStorage() trước?
  2. Không dùng typeof appifio_client === 'undefined'?
  3. Không check if (appifio_client.appifio_readFile) để biết ready?
  4. Format ngày dùng AM08, không tự parse CMS settings?

DINHDANH Creator · Loạt Method · AM09