Cocos Game Developer: từ JD đến offer 🏠
🏠 Trang chủ / Cocos Game Developer: từ JD đến offer / Phần 3 · Native, SDK, build & phát hành / Module 15
🔌 Module 15 / 21 · 1 tuần Nâng cao

Tích hợp SDK: quảng cáo, analytics, mua trong ứng dụng, đăng nhập mạng xã hội

Kiến trúc lớp bọc SDK (interface TS → adapter nền tảng → bridge → SDK, có bản giả), luồng quảng cáo nhận thưởng và mediation, đồng ý quyền riêng tư (GDPR/ ATT), thiết kế sự kiện analytics, luồng IAP an toàn có xác thực server và khôi phục giao dịch, đăng nhập Google/ Apple/ Facebook và yêu cầu của store.

Ads mediationRewardedFirebase AnalyticsIAPServer verificationSocial login
🎯 Dòng JD mà module này giúp bạn đáp ứng
  • “Integrate third-party SDKs”
  • “Proven experience integrating mobile SDKs (Ads, Analytics, IAP, Social Login)”
📌 Vì sao nhà tuyển dụng hỏi phần này

Doanh thu game casual đến gần như hoàn toàn từ quảng cáo và IAP: lỗi ở đây là mất tiền trực tiếp (người chơi xem quảng cáo không nhận thưởng, giao dịch bị hoàn tiền, bị hack nhận vật phẩm miễn phí). Người phỏng vấn kiểm tra cả kỹ thuật lẫn hiểu biết sản phẩm: bạn có nghĩ tới timeout, giao dịch treo, xác thực server, chính sách store hay không.

🎯 Mục tiêu học tập

  • Thiết kế lớp bọc SDK độc lập nền tảng
  • Cài luồng rewarded ads có timeout và trạng thái
  • Xử lý đồng ý quyền riêng tư (UMP/ ATT)
  • Thiết kế sự kiện analytics có quy ước
  • Cài luồng IAP an toàn và đăng nhập mạng xã hội đúng chính sách

🟢 Kiến trúc lớp bọc SDK

Mỗi tầng một trách nhiệm
GameplayChỉ biết IAdService/ IIapService/ IAnalytics
Adapter TSHàng đợi khi chưa init, timeout, log
BridgeJSON qua JsbBridge/ JNI/ ObjC (M13–14)
Native wrapperJava/Kotlin, ObjC/Swift gọi SDK
SDKAdMob/ MAX, Firebase, Billing, StoreKit
  • Bản giả cho editor/ web: phát triển gameplay không cần thiết bị, test luồng phần thưởng ngay.
  • Mọi lệnh gửi trước khi SDK khởi tạo xong được xếp hàng hoặc trả lỗi rõ ràng, không im lặng.
  • Một giao thức JSON có version giữa script và native giúp thêm tính năng không phá bản cũ.

🟡 Quảng cáo nhận thưởng: luồng đầy đủ

export type RewardResult = 'rewarded' | 'skipped' | 'failed' | 'timeout';

export class RewardedAds {
    private busy = false;
    constructor(private readonly native: IAdBridge, private readonly analytics: IAnalytics) {}

    async show(placement: string): Promise<RewardResult> {
        if (this.busy) return 'failed';                              // chống bấm đúp/ hai quảng cáo chồng
        if (!this.native.isReady(placement)) { this.native.load(placement); return 'failed'; }
        this.busy = true;
        AudioService.pauseAll();                                       // tắt âm thanh game khi quảng cáo chạy
        this.analytics.log('ad_rewarded_show', { placement });
        try {
            const res = await withTimeout(this.native.showRewarded(placement), 90_000, 'timeout');
            this.analytics.log('ad_rewarded_result', { placement, res });
            return res;
        } finally {
            this.busy = false;
            AudioService.resumeAll();
            this.native.load(placement);                               // nạp sẵn cho lần sau
        }
    }
}

function withTimeout<T>(p: Promise<T>, ms: number, onTimeout: T): Promise<T> {
    return Promise.race([p, new Promise<T>(r => setTimeout(() => r(onTimeout), ms))]);
}
// Phát thưởng CHỈ khi nhận callback "rewarded" (không phải "closed").
// Phần thưởng giá trị cao: dùng server-side verification (SSV) của mạng quảng cáo để server cộng thưởng.
Chủ đềThực hành tốt
MediationMột SDK điều phối (AdMob mediation, AppLovin MAX, LevelPlay…) đấu giá giữa nhiều mạng để tăng doanh thu; cập nhật adapter đồng bộ phiên bản
Tần suấtGiới hạn interstitial (VD không quá 1 lần/ 2–3 phút, không ngay khi mở game), điều khiển bằng remote config
Trải nghiệmKhông hiện quảng cáo giữa thao tác; nút xem quảng cáo chỉ hiện khi đã sẵn sàng
Doanh thuGhi sự kiện ad_impression kèm doanh thu (nếu SDK cung cấp) vào analytics để tính LTV

🟡 Quyền riêng tư và đồng ý

Yêu cầuÁp dụngCách làm
Đồng ý GDPR/ khu vực có luật tương tựNgười dùng ở EEA, Anh… (và quy định nơi khác)Nền tảng quản lý đồng ý (VD Google UMP) hiển thị trước khi khởi tạo quảng cáo cá nhân hoá
App Tracking Transparency (iOS)Theo dõi qua app/ IDFAHiện hộp thoại ATT trước khi SDK dùng IDFA; tôn trọng từ chối
Quảng cáo cho trẻ emGame hướng trẻ emCờ hạn chế nội dung/ không cá nhân hoá theo chính sách SDK và store
Khai báo storeData safety (Play), Privacy nutrition label (App Store)Khai đúng dữ liệu mọi SDK thu thập
Thứ tự khởi tạo

Hiển thị đồng ý (UMP) → ATT (iOS) → khởi tạo SDK quảng cáo/ analytics với cấu hình tương ứng. Khởi tạo quảng cáo trước khi có đồng ý là lỗi tuân thủ hay gặp.

🟡 Analytics: sự kiện có quy ước

Sự kiệnTham sốTrả lời câu hỏi
tutorial_stepstep (1..n)Người chơi rơi rụng ở bước nào?
level_start / level_endlevel, result (win/lose/quit), moves_left, duration_s, boosters_usedMàn nào quá khó?
ad_rewarded_resultplacement, resultVị trí quảng cáo nào hiệu quả?
purchaseproduct_id, price, currency (store cung cấp)Doanh thu theo gói
economy_changecurrency, delta, source/sinkKinh tế tiền ảo có lạm phát?
  • Tên sự kiện chữ thường, gạch dưới, ổn định; mỗi sự kiện có tài liệu định nghĩa (giống thẻ chỉ số).
  • Không gửi dữ liệu cá nhân (email, tên) vào analytics.
  • Chú ý giới hạn số sự kiện/ tham số của nền tảng analytics; kiểm tra bằng chế độ debug view trước khi phát hành.

🔴 IAP: luồng an toàn

Không cộng vật phẩm chỉ dựa trên client
Truy vấn sản phẩmLấy giá đã định dạng từ store
MuaStore xử lý thanh toán
Gửi biên nhận lên serverpurchase token/ transaction
Server xác thực với storeGoogle Play Developer API/ App Store Server API
Cộng vật phẩm (luỹ đẳng theo mã giao dịch)
Xác nhận/ kết thúc giao dịchacknowledge/ consume, finishTransaction
Chi tiếtVì sao quan trọng
Google Play: acknowledge (hoặc consume) giao dịch trong thời hạn quy định (vài ngày)Không xác nhận → giao dịch tự hoàn tiền
StoreKit: finishTransaction sau khi đã cộng vật phẩmKhông finish → giao dịch lặp lại mỗi lần mở app; finish quá sớm → mất vật phẩm nếu app crash
Xử lý giao dịch treo/ đang chờ (pending) khi mở appNgười chơi đã trả tiền nhưng app crash giữa chừng
Cộng vật phẩm luỹ đẳng theo orderId/ transactionIdCallback có thể đến nhiều lần
Khôi phục giao dịch (Restore Purchases)Bắt buộc với non-consumable/ subscription trên iOS
Giá hiển thị lấy từ storeĐúng tiền tệ, thuế từng quốc gia
// Rút gọn: client chỉ là người đưa tin, server là người quyết định
async function buy(productId: string) {
    const purchase = await iap.purchase(productId);                  // native trả token/ receipt
    const res = await api.post('/iap/verify', { productId, token: purchase.token, platform: purchase.platform });
    if (res.ok) {
        inventory.applyServerState(res.inventory);                    // nhận trạng thái từ server, không tự cộng
        await iap.finish(purchase);                                   // acknowledge/ consume/ finishTransaction
    }
}
// Khi mở app: iap.getPendingPurchases() → xác thực lại từng giao dịch còn treo

🟡 Đăng nhập mạng xã hội

Phương thứcLưu ý
Google (Android)Thư viện đăng nhập hiện hành của Google (Credential Manager); gửi ID token lên server để xác minh chữ ký
Sign in with AppleApp Store Review Guidelines (mục Login Services) yêu cầu cung cấp tuỳ chọn đăng nhập đáp ứng các yêu cầu quyền riêng tư khi app dùng đăng nhập bên thứ ba; Sign in with Apple là lựa chọn phổ biến — đọc bản guideline mới nhất
FacebookCấu hình key hash/ bundle id; phiên bản SDK và quyền tối thiểu
Tài khoản khách → liên kếtCho chơi ngay bằng tài khoản khách, liên kết sau để giữ tiến trình; xử lý xung đột khi tài khoản đã có tiến trình
Xoá tài khoảnApp cho phép tạo tài khoản phải cho phép xoá tài khoản ngay trong app (yêu cầu của App Store)
Xác minh ở server

Token đăng nhập phải được server xác minh (chữ ký, audience, hạn) trước khi tạo phiên. Client chỉ chuyển token, không tự tin vào user id trả về từ SDK.

🎤 Câu hỏi phỏng vấn thường gặp (trả lời to trước khi mở)

🎤 Thiết kế lớp tích hợp quảng cáo để sau này đổi từ AdMob sang AppLovin MAX dễ dàng.
Interface IAdService (load/ isReady/ show trả Promise kết quả) cho gameplay; adapter TS xử lý hàng đợi, timeout, analytics; bridge JSON; wrapper native cho từng SDK; bản giả cho editor. Đổi SDK chỉ thay wrapper native + cấu hình, gameplay không đổi.
🎤 Người chơi báo xem quảng cáo xong không nhận thưởng. Bạn điều tra thế nào?
Kiểm tra analytics: tỷ lệ show → rewarded; log callback; nghi phát thưởng ở callback closed hay rewarded, callback về sai luồng, node đã huỷ khi callback đến (isValid), timeout quá ngắn, scene chuyển giữa chừng. Giải pháp: phần thưởng do service cấp (không gắn vào popup), lưu trạng thái chờ thưởng, SSV cho thưởng giá trị cao.
🎤 Mô tả luồng IAP an toàn của bạn.
Truy vấn sản phẩm → mua → gửi token lên server → server xác thực với API của store → cộng vật phẩm luỹ đẳng theo mã giao dịch → client nhận trạng thái → acknowledge/consume/finish → xử lý giao dịch treo khi mở app → restore cho non-consumable. Nêu thời hạn acknowledge của Google và hậu quả finish sai thời điểm của StoreKit.
🎤 Analytics bạn thiết kế gồm những sự kiện nào cho một game puzzle mới?
Tutorial funnel, level_start/end với kết quả và thời gian, booster dùng, nguồn/ đích tiền tệ, quảng cáo (vị trí, kết quả, doanh thu), IAP, retention tự động; quy ước tên, tài liệu sự kiện, không PII, kiểm tra debug view.
🎤 Cần chú ý gì về quyền riêng tư khi tích hợp quảng cáo?
Đồng ý GDPR (UMP) trước khi cá nhân hoá, ATT trên iOS, cờ trẻ em nếu áp dụng, khai báo Data safety/ privacy label đúng với SDK, privacy manifest của SDK iOS, không gửi PII vào analytics.

⚠️ Sai lầm thường mắc

❌ Phát thưởng ở callback đóng quảng cáo

Vì sao nguy hiểm: Người chơi bỏ giữa chừng vẫn nhận thưởng.

Cách làm đúng: Chỉ phát ở callback rewarded (hoặc SSV).

❌ Cộng vật phẩm IAP chỉ ở client

Vì sao nguy hiểm: Bị hack, giao dịch giả.

Cách làm đúng: Xác thực server, luỹ đẳng.

❌ Không acknowledge/ finish đúng

Vì sao nguy hiểm: Hoàn tiền tự động hoặc mất vật phẩm.

Cách làm đúng: Theo luồng chuẩn, xử lý giao dịch treo.

❌ Khởi tạo quảng cáo trước khi có đồng ý

Vì sao nguy hiểm: Vi phạm quyền riêng tư.

Cách làm đúng: UMP → ATT → init.

❌ Gameplay gọi SDK trực tiếp

Vì sao nguy hiểm: Khó đổi SDK, không test được.

Cách làm đúng: Interface + adapter + bản giả.

❌ Không có timeout

Vì sao nguy hiểm: Treo chờ callback mãi.

Cách làm đúng: Timeout + trạng thái rõ ràng.

📌 Cần nhớ
  • Gameplay → interface → adapter → bridge → wrapper native → SDK; có bản giả.
  • Rewarded: chống bấm đúp, tắt âm, timeout, thưởng ở callback rewarded/ SSV.
  • Đồng ý quyền riêng tư trước khi khởi tạo quảng cáo; ATT trên iOS.
  • IAP: server xác thực, luỹ đẳng, acknowledge/ finish đúng lúc, xử lý treo, restore.
  • Đăng nhập: server xác minh token; tuân thủ yêu cầu login và xoá tài khoản của store.

🧩 Tự kiểm tra (bấm để xem đáp án)

1. Phát thưởng quảng cáo nên dựa vào:
A. Callback closed
B. Callback rewarded hoặc SSV
C. Thời gian xem
Đáp án: B. Đúng điều kiện nhận thưởng.
2. Giao dịch Google Play không được acknowledge trong thời hạn sẽ:
A. Vẫn bình thường
B. Tự hoàn tiền
C. Bị khoá tài khoản
Đáp án: B. Chính sách Play Billing.
3. Cộng vật phẩm luỹ đẳng nghĩa là:
A. Cộng mỗi lần callback
B. Dùng mã giao dịch để chỉ cộng một lần
C. Không cộng
Đáp án: B. Callback có thể lặp.
4. Thứ tự đúng trên iOS:
A. Init quảng cáo → ATT
B. Đồng ý (UMP) → ATT → init SDK
C. Không cần đồng ý
Đáp án: B. Tuân thủ quyền riêng tư.
5. Token đăng nhập Google nên:
A. Tin user id từ client
B. Gửi lên server xác minh
C. Lưu vào analytics
Đáp án: B. Server xác minh.

🏋️ Bài tập thực hành

Bộ SDK service hoàn chỉnh với bản giả

Viết IAdService, IIapService, IAnalytics, IAuthService (TS) + bản giả có độ trễ và lỗi ngẫu nhiên có seed. Dựng màn test: xem quảng cáo nhận x2 xu, mua gói xu (giả server xác thực), giao dịch treo được xử lý lại khi khởi động, đăng nhập khách → liên kết. Nếu có thiết bị: thay bản giả quảng cáo bằng AdMob test ad unit.

💡 Gợi ý lời giải
Bản giả phải mô phỏng cả trường hợp xấu: không sẵn sàng, bỏ giữa chừng, timeout, callback đến hai lần, app “crash” giữa lúc mua (lưu pending vào storage rồi reload). Đây là cách chứng minh bạn nghĩ tới các ca biên mà người phỏng vấn hay hỏi.

📚 Tài nguyên học tập

✅ Tự đánh giá hoàn thành

  • Vẽ kiến trúc lớp bọc SDK
  • Viết luồng rewarded có timeout
  • Liệt kê yêu cầu quyền riêng tư
  • Thiết kế bộ sự kiện analytics
  • Viết luồng IAP xác thực server
Lưu ý: Cocos Creator, Cocos2d-x, Spine, SDK của Google/ Apple/ các mạng quảng cáo thay đổi API theo phiên bản. Code mẫu viết cho Cocos Creator 3.8.x và Cocos2d-x 3.17/4.0; luôn đối chiếu tài liệu chính thức của phiên bản dự án bạn đang dùng. Chính sách App Store/ Google Play (đăng nhập, quyền riêng tư, tải code, target API) được tóm tắt ở mức tham khảo, hãy đọc bản mới nhất trước khi phát hành. Khoá học độc lập, không liên kết với Cocos, Esoteric Software hay nhà tuyển dụng nào.