Readme

Facebook Instant Games Plugin

Thư viện plugin tích hợp Facebook Instant Games cho Unity WebGL.

Cấu trúc thư mục

CSCMobiPlugin/FacebookInstant/
├── Scripts/
│   ├── FbInstant.cs              # Main controller (MonoBehaviour)
│   ├── FbPlayer.cs               # Player Data & Subscribe
│   ├── FbPayment.cs              # In-App Purchase
│   ├── FbInterstitial.cs         # Interstitial Ads
│   ├── FbRewardedVideo.cs       # Rewarded Video Ads
│   ├── FbShare.cs                # Share functionality
│   ├── FbInvite.cs               # Invite functionality
│   ├── FbCommunity.cs            # Community (Follow Page, Join Group)
│   ├── FbTournament.cs           # Tournament functionality
│   ├── FbNotification.cs         # Push Notifications
│   ├── FbContext.cs              # Context (getID, switchAsync, createAsync, getPlayersAsync, chooseAsync)
│   ├── FbInstantLogEvent.cs      # Analytics (LogEvent)
│   └── Models/
│       ├── CustomUpdateModels.cs  # CustomUpdateWithOverlayPayload, LocalizableContent, MediaParams
│       ├── ContextPlayer.cs       # ContextPlayer structure
│       ├── ChooseContextOptions.cs # ChooseContextOptions structure
│       └── TournamentModels.cs    # Tournament models (TournamentInfo, CreateTournamentPayload, etc.)
├── Prefabs/
│   ├── FbInstant.prefab          # Prefab đã cấu hình sẵn (khuyến nghị sử dụng)
│   └── FBProductCatalog.prefab   # Prefab quản lý Product Catalog
├── Plugins/
│   ├── facebookinstant.jslib    # JavaScript Bridge (Social Features, Entry Point, Update, LogEvent)
│   ├── Context.jslib            # JavaScript Bridge (Context APIs)
│   ├── FbCommunity.jslib         # JavaScript Bridge (Community)
│   ├── FbTournament.jslib        # JavaScript Bridge (Tournament)
│   ├── Player.jslib              # JavaScript Bridge (Player Data, Subscribe)
│   ├── Payment.jslib              # JavaScript Bridge (IAP)
│   ├── Share.jslib               # JavaScript Bridge (Share)
│   ├── Invite.jslib              # JavaScript Bridge (Invite)
│   ├── AdsInterstitial.jslib     # JavaScript Bridge (Interstitial)
│   └── AdsRewardedVideo.jslib    # JavaScript Bridge (Rewarded Video)
├── JavaScript/
│   ├── FacebookInstant.js        # Main JavaScript (Social Features, Entry Point, Update, LogEvent)
│   ├── FbContext.js              # Context Features
│   ├── FbCommunity.js           # Community Features
│   ├── FbTournament.js          # Tournament Features
│   ├── FbPlayer.js               # Player Data & Subscribe
│   ├── FbPayment.js              # IAP
│   ├── FbInterstitial.js        # Interstitial Ads
│   ├── FbRewardedVideo.js        # Rewarded Video Ads
│   ├── FbShare.js                # Share
│   ├── FbInvite.js               # Invite
│   ├── FbGSM.js                  # GSM Config, Login, Init, Analytics
│   └── FbInit.js                 # Initialization
├── Configs/
│   ├── fbapp-config_LANDSCAPE.json
│   └── fbapp-config_PORTRAIT.json
├── Common/
│   ├── IAP/
│   │   ├── FBProductCatalogController.cs  # Controller quản lý Product Catalog
│   │   └── IAPBtnController.cs            # Controller cho IAP Button
│   ├── Notification/
│   │   └── FBPushNotificationController.cs # Controller quản lý Push Notifications
│   └── Social/
│       └── FbSocialBtnController.cs       # Base controller cho social buttons
└── Editor/
    └── PostProcessWebGLBuild.cs  # Auto post-process build

Tính năng

  • Player Data: Lưu/tải dữ liệu cloud với debouncing

  • Subscribe: Subscribe to bot

  • Share: Chia sẻ hình ảnh/game với position tracking

  • Invite: Mời bạn bè chơi game

  • Interstitial Ads: Quảng cáo toàn màn hình

  • Reward Video Ads: Quảng cáo video có thưởng

  • IAP (In-App Purchase): Mua hàng trong ứng dụng với đầy đủ thông tin purchase

  • Get Catalog: Lấy danh sách products có sẵn với giá và thông tin địa phương hóa

  • Social Features: Pin game (Create Shortcut)

  • Community: Follow official page, Join official group

  • Tournament: Tạo, tham gia, đăng điểm, chia sẻ tournament với callbacks tùy chọn

  • Post Session Score: Đăng điểm session với callbacks

  • Push Notifications: Gửi và hủy push notifications đến players

  • Product Catalog: Quản lý và hiển thị danh sách products với giá từ Facebook

  • Context: Quản lý game context (getID, switchAsync, createAsync, getPlayersAsync, chooseAsync)

  • Analytics: Log events với FB Analytics (LogEvent)

  • Entry Point: Lấy entry point data và name (GetEntryPointData, GetEntryPointAsync)

  • Update: Gửi custom update với overlay (UpdateAsync)

  • Lifecycle Events: Xử lý pause event (OnPause)

  • GSM Integration: Tích hợp GSM system (Config, Login, Init, Analytics Events, Funnel Events)

Cài đặt

1. Setup Prefab trong Scene

Cách 1: Sử dụng Prefab (Khuyến nghị)

  1. Tìm prefab FbInstant trong thư mục Assets/CSCMobiPlugin/FacebookInstant/Prefabs/

  2. Kéo prefab FbInstant vào scene đầu tiên (thường là Splash/Login scene)

  3. Prefab đã được cấu hình sẵn với script FbInstantenableEditorTesting = true

  4. GameObject sẽ tự động được đặt tên "FbInstant" trong Awake() và được DontDestroyOnLoad để tồn tại qua các scene

Cách 2: Tạo GameObject thủ công

Nếu không sử dụng prefab:

  • Tạo GameObject mới trong scene

  • Add Component: FbInstant

  • GameObject sẽ tự động được đặt tên "FbInstant" khi khởi tạo

  • Enable enableEditorTesting trong Inspector nếu muốn test trong Editor

2. Build WebGL

Plugin sẽ tự động:

  • Tự động phát hiện và copy tất cả các file JavaScript từ thư mục JavaScript/ vào js/ folder

  • Copy file config (fbapp-config.json) dựa trên orientation (Landscape/Portrait)

  • Modify index.html để thêm script tags cho tất cả file JS

  • Replace Unity loader script với Facebook Instant Games initialization

Lưu ý:

  • File config sẽ được copy tự động:

    • Nếu Resolution Width > Height → Copy fbapp-config_LANDSCAPE.jsonfbapp-config.json

    • Nếu Resolution Height >= Width → Copy fbapp-config_PORTRAIT.jsonfbapp-config.json

  • Không cần khai báo thủ công danh sách file JavaScript, plugin sẽ tự động tìm tất cả file .js trong thư mục JavaScript/

3. Khởi tạo trong Unity

FbInstant sẽ tự động khởi tạo trong Start():

Sử dụng

Player Data

Lưu ý: SetData sử dụng debouncing (500ms) để batch multiple updates. Sử dụng SetDataImmediate cho critical saves.

Subscribe

Lưu ý:

  • position là tham số tùy chọn (mặc định là empty string) để tracking vị trí người dùng thực hiện action

  • OnSubscribed nhận position để tracking

Share

Invite

Interstitial Ads

Rewarded Video Ads

IAP (In-App Purchase)

Purchase (Mua hàng)

PurchaseInfo Structure

PurchaseInfo class chứa đầy đủ thông tin từ Facebook Instant Games:

Get Catalog (Lấy danh sách products)

ProductCatalog Structure

ProductCatalog class chứa thông tin product từ catalog:

Lưu ý:

  • Sử dụng pricepriceCurrencyCode để hiển thị giá cho người dùng

  • priceAmount là số tiền dạng số để tính toán

  • Catalog được lấy từ FBInstant.payments.getCatalogAsync() API

Social Features

Lưu ý:

  • position là tham số tùy chọn (mặc định là empty string) để tracking vị trí người dùng thực hiện action

  • OnCreateShortcutCompleted nhận position để tracking

Update (Custom Update with Overlay)

Lưu ý:

  • CustomUpdateWithOverlayPayload hỗ trợ nhiều tùy chọn như image, imageOverlayPath, media, notificationText, etc.

  • Xem CustomUpdateModels.cs để biết đầy đủ các thuộc tính có sẵn

  • strategy có thể là: "IMMEDIATE", "LAST", hoặc "IMMEDIATE_CLEAR"

  • notification có thể là: "NO_PUSH" hoặc "PUSH"

Context Features

Lưu ý:

  • Context ID sẽ là null nếu game đang ở solo context

  • GetID() không nên được gọi cho đến khi FBInstant.startGameAsync đã hoàn thành

  • GetPlayersAsync() trả về danh sách players đã chơi trong context trong 90 ngày gần nhất

  • ChooseAsync() mở dialog để player chọn context, có thể reject nếu player hủy

Community Features

Lưu ý:

  • position là tham số tùy chọn (mặc định là empty string) để tracking vị trí người dùng thực hiện action

  • OnFollowPageSuccessOnJoinGroupSuccess nhận position để tracking

Tournament Features

Create Tournament

Join Tournament

Post Tournament Score

Get Tournaments List

Share Tournament

Lưu ý:

  • Tất cả callbacks trong Tournament features là tùy chọn (có thể truyền null)

  • position là tham số riêng, không nằm trong payload

  • OnShareClick được trigger trước khi share dialog mở

  • OnShareTournamentSuccess nhận position để tracking

Post Session Score

Lưu ý:

  • PostSessionScoreAsync sử dụng FBInstant.postSessionScoreAsync API

  • Callbacks là tùy chọn (có thể truyền null)

Push Notifications

Lưu ý quan trọng: Push Notifications sử dụng UnityWebRequest để gọi Facebook API trực tiếp từ C#, không cần JavaScript bridge.

Setup

Gửi Notification

Hủy Notification

Lưu ý quan trọng:

  • scheduleSeconds: PHẢI >= 300 giây (5 phút), nếu < 300 sẽ báo lỗi

  • playerId: Bắt buộc, phải truyền vào làm tham số

  • accessToken: Bắt buộc, phải lấy từ GetAccessToken() trước

  • appId: Bắt buộc, Facebook App ID

  • label: Optional, dùng để nhóm notifications

  • notification_id: Có thể rỗng, tùy thuộc vào response từ Facebook API

  • success: Có thể là true hoặc false tùy vào kết quả

  • Không cần .jslib và .js files: Sử dụng UnityWebRequest trực tiếp từ C#

Product Catalog Management

Sử dụng FBProductCatalog Prefab

Cách 1: Sử dụng Prefab (Khuyến nghị)

  1. Tìm prefab FBProductCatalog trong thư mục Assets/CSCMobiPlugin/FacebookInstant/Prefabs/

  2. Kéo prefab vào scene (thường là scene đầu tiên hoặc IAP scene)

  3. Prefab đã được cấu hình sẵn với script FBProductCatalogController

  4. Catalog sẽ tự động load từ Facebook khi Start() được gọi

Cách 2: Tạo GameObject thủ công

Sử dụng FBProductCatalogController

Sử dụng IAPBtnController

IAPBtnController tự động cập nhật giá từ FBProductCatalogController:

  1. Thêm component vào Button:

    • Thêm component IAPBtnController vào GameObject có Button

    • Set productID trong Inspector (ví dụ: "com.yourgame.ruby100")

    • Assign TextMeshProUGUI component vào priceText field

  2. Tự động cập nhật giá:

    • Giá sẽ tự động được cập nhật khi:

      • GameObject được enable (OnEnable())

      • Component được start (Start())

    • Giá được lấy từ FBProductCatalogController.Instance.GetFormattedPrice(productID)

Ví dụ setup:

Lưu ý:

  • IAPBtnController cần FBProductCatalogController.Instance đã được khởi tạo

  • Đảm bảo FBProductCatalog prefab đã được thêm vào scene trước khi sử dụng

  • Catalog sẽ tự động load từ Facebook khi FBProductCatalogController start

  • Nếu catalog chưa load, giá sẽ không được hiển thị (cần đợi catalog load xong)

Start Game Event

Lưu ý:

  • Event này được trigger sau khi FBInstant.startGameAsync() hoàn thành

  • PlayerID đã được set tự động trong FbInstant.Instance.PlayerID

  • Platform detection (OnGetPlatform()) cũng được gọi tự động sau khi game ready

Entry Point

Lưu ý:

  • GetEntryPointData() trả về null cho mobile clients cũ hoặc khi không có data

  • GetEntryPointAsync() không nên được gọi cho đến khi FBInstant.startGameAsync đã hoàn thành

  • Entry point data có thể chứa thông tin từ updateAsync() payload

Analytics (LogEvent)

Lưu ý:

  • Event name phải từ 2 đến 40 ký tự

  • Event name chỉ có thể chứa: _, -, (space), và alphanumeric characters

  • Parameters tối đa 25 cặp key-value

  • Parameter keys phải từ 2-40 ký tự, cùng format như event name

  • Parameter values phải ít hơn 100 ký tự

  • Method trả về null nếu thành công, hoặc error message nếu thất bại

Lifecycle Events (OnPause)

Lưu ý:

  • Event này được trigger khi user chuyển sang window/tab khác (desktop) hoặc chuyển app (mobile)

  • Được đăng ký tự động trong FbInit.js sau khi startGameAsync hoàn thành

  • Nên sử dụng để lưu game state hoặc pause gameplay

GSM Integration

GSM (Game Service Management) là hệ thống quản lý và analytics cho game. Plugin tự động tích hợp GSM khi có cấu hình.

Auto-Initialization

GSM sẽ tự động khởi tạo nếu:

  • window.gsmAppId được set (tự động từ PostProcessWebGLBuild nếu có GSM AppId trong Project Settings)

  • window.appVersion được set (tự động từ Product Version trong Project Settings)

Lưu ý:

  • GSM sẽ tự động init sau khi FBInstant.initializeAsync() hoàn thành

  • Sử dụng FBInstant.player.getID() làm deviceIdFBInstant.getPlatform() làm userClassify

  • Access Token sẽ tự động được gửi về Unity qua FbInstant.Instance.GSMAccessToken

GSM Access Token

Lưu ý:

  • GSM Access Token chỉ có sẵn sau khi initGSM hoàn thành thành công

  • Token được lưu tự động trong FbInstant.Instance.GSMAccessToken

  • Nếu GSM không được init (thiếu gsmAppId hoặc appVersion), token sẽ là null hoặc empty

GSM Functions (JavaScript)

Các hàm GSM được định nghĩa trong FbGSM.js:

  1. getGSMConfig(appId, deviceId): Lấy cấu hình GSM từ API

  2. loginGSM(appId, deviceId, version, userClassify): Đăng nhập vào hệ thống GSM

  3. initGSM(appId, deviceId, version, userClassify): Khởi tạo GSM (gọi config rồi login)

  4. gsmSendEvent(eventName, parameters): Gửi event analytics đến GSM

  5. sendFunnel(funnelName, priority, actionName): Gửi funnel event đến GSM

Lưu ý:

  • Các hàm này được gọi tự động từ JavaScript trong FbInit.js

  • initGSM được gọi tự động nếu có window.gsmAppIdwindow.appVersion

  • sendFunnel được gọi tự động trong quá trình loading game (FbLoading funnel)

  • Events được queue nếu access token chưa sẵn sàng và sẽ được gửi sau khi login thành công

Loading Funnel Events

Plugin tự động gửi các funnel events trong quá trình loading:

  • FbLoading funnel với các actions:

    • Priority 1: "1.Start Load" - Khi bắt đầu load

    • Priority 2: "2.1.Load 30%" - Khi load đạt 30%

    • Priority 2: "2.2.Load 50%" - Khi load đạt 50%

    • Priority 2: "2.3.Load 70%" - Khi load đạt 70%

    • Priority 2: "2.4.Load 90%" - Khi load đạt 90%

    • Priority 3: "3.LoadSuccess" - Khi load thành công

    • Priority 4: "4.StartGameSuccess" - Khi startGameAsync thành công

Lưu ý:

  • Funnel events được gửi tự động, không cần gọi thủ công

  • Events sẽ được queue nếu GSM chưa init và sẽ được gửi sau khi login thành công

Player Information

Events Reference

Player Data Events

Ads Events

IAP Events

Share & Invite Events

Community Events

Tournament Events

Notification Events

Social Features Events

Context Events

Entry Point Events

Lifecycle Events

Start Game Event

Static Properties Access

Tất cả các module được truy cập qua static properties:

Editor Mode Testing

Plugin hỗ trợ testing trong Unity Editor:

  1. Nếu sử dụng Prefab: Prefab đã được cấu hình sẵn với enableEditorTesting = true

  2. Nếu tạo GameObject thủ công: Enable enableEditorTesting trong Inspector của FbInstant GameObject

  3. Các tính năng sẽ được simulate (không thực sự gọi Facebook API)

  4. Events vẫn hoạt động bình thường để test logic

Lưu ý:

  • Editor mode chỉ simulate, không thực sự lưu data hoặc hiển thị ads

  • Prefab mặc định đã enable Editor Testing để dễ dàng test ngay

Post-Process Build

Plugin tự động xử lý sau khi build WebGL:

  1. Tự động phát hiện và copy JavaScript files:

    • Tự động quét thư mục JavaScript/ để tìm tất cả file .js

    • Copy tất cả file .js vào js/ folder trong build

    • Không cần khai báo thủ công danh sách file

  2. Copy Config file: Tự động copy fbapp-config.json dựa trên orientation

  3. Modify index.html: Tự động thêm script tags cho tất cả file JavaScript

  4. Replace Unity loader: Tự động thay thế Unity loader script với Facebook Instant Games initialization

Config file tự động:

  • Dựa trên Resolution Width/Height trong Project Settings

  • Landscape (Width > Height) → fbapp-config_LANDSCAPE.json

  • Portrait (Height >= Width) → fbapp-config_PORTRAIT.json

GSM Configuration:

  • Nếu có GSM AppId trong Project Settings, window.gsmAppId sẽ tự động được thêm vào index.html

  • window.appVersion sẽ tự động được thêm từ Product Version trong Project Settings

  • GSM sẽ tự động init nếu cả hai giá trị này đều có sẵn

Lưu ý:

  • Plugin tự động phát hiện tất cả file .js trong thư mục JavaScript/

  • File được sắp xếp theo tên để đảm bảo thứ tự nhất quán

  • File .meta sẽ tự động bị bỏ qua

Lưu ý quan trọng

  1. Facebook Instant Games SDK 8.0: Plugin sử dụng Facebook Instant Games SDK 8.0

  2. Chỉ hoạt động trên WebGL: Plugin chỉ hoạt động khi build WebGL, không hoạt động trong Unity Editor (trừ Editor Testing mode)

  3. GameObject Name: GameObject sẽ tự động được đặt tên "FbInstant" trong Awake() để JavaScript có thể gọi SendMessage

  4. DontDestroyOnLoad: FbInstant GameObject sẽ tồn tại qua các scene

  5. Debouncing: Player Data sử dụng debouncing (500ms) để batch multiple updates

  6. Ad Unit IDs: Cần cấu hình Ad Unit IDs cho Interstitial và Rewarded Video

  7. Product IDs: Product IDs cho IAP phải được tạo trong Facebook App Dashboard

  8. Auto-reload Ads: Ads sẽ tự động reload sau khi hiển thị (cần gọi Load lại)

  9. Callbacks tùy chọn: Tất cả callbacks trong Tournament features và PostSessionScoreAsync là tùy chọn (có thể truyền null)

Troubleshooting

SendMessage: object FbInstant not found!

  • Đảm bảo GameObject có script FbInstant được đặt trong scene đầu tiên

  • GameObject sẽ tự động được đặt tên "FbInstant" trong Awake()

Ads không hiển thị

  • Kiểm tra Ad Unit IDs đã đúng chưa

  • Kiểm tra Console log để xem lỗi

  • Đảm bảo đã gọi LoadInterstitial/LoadRewardedVideo trước khi show

  • Kiểm tra IsInterstitialReady/IsRewardedVideoReady trước khi show

IAP không hoạt động

  • Kiểm tra Product ID đã đúng chưa

  • Kiểm tra payments.onReady đã được gọi chưa

  • Xem Console log để debug

  • Sử dụng GetCatalogAsync() để lấy danh sách products có sẵn và kiểm tra Product IDs

  • Kiểm tra PurchaseInfo có đầy đủ thông tin không (purchaseToken, paymentID, signedRequest, etc.)

Share/Invite không hoạt động

  • Đảm bảo game đang chạy trong Facebook Instant Games environment

  • Kiểm tra permissions trong Facebook App settings

Data không lưu

  • Sử dụng SetDataImmediate cho critical saves

  • Gọi FlushPendingUpdates() trước khi game exit

  • Kiểm tra IsDataGameDone() để đảm bảo data đã load xong

Community features không hoạt động

  • Đảm bảo game đang chạy trong Facebook Instant Games environment

  • Kiểm tra official page/group đã được cấu hình trong Facebook App Dashboard

  • Kiểm tra Console log để xem lỗi chi tiết

Tournament không hoạt động

  • Đảm bảo game đang chạy trong Facebook Instant Games environment

  • Kiểm tra Console log để xem lỗi chi tiết

  • Callbacks là tùy chọn, có thể truyền null nếu không cần

Notification không gửi được

  • Đảm bảo đã gọi SetCoroutineRunner() trước khi sử dụng

  • Đảm bảo đã lấy Access Token từ GetAccessToken() trước khi gửi

  • Kiểm tra App ID và App Secret đã đúng chưa

  • Kiểm tra scheduleSeconds PHẢI >= 300 giây (5 phút), nếu < 300 sẽ báo lỗi

  • Kiểm tra playerId đã được truyền vào chưa (bắt buộc)

  • Kiểm tra accessToken không null hoặc empty

  • Xem Console log để xem lỗi chi tiết từ Facebook API

  • Đảm bảo FbInstant.Instance đã được khởi tạo

Product Catalog không hiển thị giá

  • Đảm bảo FBProductCatalog prefab đã được thêm vào scene

  • Kiểm tra FBProductCatalogController.Instance.IsCatalogLoaded() để xem catalog đã load chưa

  • Gọi FBProductCatalogController.Instance.LoadCatalogFromFbInstant() để reload catalog

  • Kiểm tra Product ID đã đúng chưa (phải khớp với Product ID trong Facebook App Dashboard)

  • Đảm bảo IAPBtnController.productID đã được set đúng trong Inspector

Context không hoạt động

  • Đảm bảo game đang chạy trong Facebook Instant Games environment

  • Kiểm tra FBInstant.startGameAsync đã hoàn thành trước khi gọi GetID() hoặc GetPlayersAsync()

  • Kiểm tra Console log để xem lỗi chi tiết

  • Đảm bảo player có quyền truy cập context (connected players)

LogEvent không hoạt động

  • Kiểm tra event name đã đúng format chưa (2-40 ký tự, chỉ chứa '_', '-', ' ', và alphanumeric)

  • Kiểm tra parameters không vượt quá 25 cặp key-value

  • Kiểm tra parameter keys và values đã đúng format chưa

  • Xem Console log để xem error message chi tiết

Entry Point không lấy được data

  • Đảm bảo FBInstant.initializeAsync() đã hoàn thành trước khi gọi GetEntryPointData()

  • Đảm bảo FBInstant.startGameAsync() đã hoàn thành trước khi gọi GetEntryPointAsync()

  • Entry point data có thể là null nếu không có data từ entry point cụ thể

  • Kiểm tra game có được launch từ entry point có data không (ví dụ: từ custom update)

GSM không init hoặc Access Token không có

  • Kiểm tra window.gsmAppId đã được set trong index.html chưa (tự động từ PostProcessWebGLBuild nếu có GSM AppId)

  • Kiểm tra window.appVersion đã được set trong index.html chưa (tự động từ Product Version)

  • Kiểm tra Console log để xem lỗi chi tiết từ GSM API

  • Đảm bảo FbGSM.js đã được load (tự động được thêm vào index.html bởi PostProcessWebGLBuild)

  • GSM sẽ tự động init sau khi FBInstant.initializeAsync() hoàn thành

  • Access Token sẽ được set tự động sau khi loginGSM thành công

License

CSCMobiPlugin - Facebook Instant Games Plugin

Support

Nếu có vấn đề, vui lòng liên hệ team phát triển.

Last updated