
DINHDANH Creator · Bài AM09 · SECTION CÁC BIẾN VÀ HÀM TOÀN CỤC
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_clientbản Aura khi backend = Advanced - Định nghĩa các hàm helper toàn cục (
waitForAppStorage, …)
<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.
| Field | Nghĩa đời thường |
|---|---|
url_name | Slug 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_url | Gốc domain platform - dùng ghép link tuyệt đối (xem AM10) |
api_key | Token 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
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

Bootstrap dùng Object.defineProperty - getter trả về proxy hoặc instance thật:
| Trạng thái | appifio_client trả về |
|---|---|
| Script client chưa load xong | proxyClient - mọi appifio_*() được xếp hàng, tự chạy khi ready |
| AppStorageClient đã khởi tạo | clientInstance thật |
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')typeof appifio_client === 'undefined'- getter luôn có, check này vô nghĩaif (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ùngwaitForAppStorage()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àm | Hà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
- Mọi trang có JS API đều
await waitForAppStorage()trước? - Không dùng
typeof appifio_client === 'undefined'? - Không check
if (appifio_client.appifio_readFile)để biết ready? - Format ngày dùng AM08, không tự parse CMS settings?
Bài tiếp theo
Điều hướng nội bộ (cùng ngôn ngữ)
DINHDANH Creator · Loạt Method · AM09