1. Tổng quan

• Định nghĩa: Là bước tích hợp gói thư viện khung .xcframework vào cấu trúc dự án Xcode và chạy các event mặc định cơ bản.
• Đối tượng sử dụng: Developer hệ điều hành iOS.

2. Giải thích Thuật ngữ & Thông số

•  FrameWork (.xcframework): Phiên bản đóng gói thư viện CSDK của hệ thống Mobio.
• App Tracking Transparency (ATT): Framework thuộc về Apple, đòi hỏi người dùng ứng dụng phải cấp quyền minh bạch cho iOS về truy cập IDFA (sử dụng thông tin quảng cáo và tracking cá nhân hóa).
• AppDelegate: Class khởi tạo điểm đầu tiên của chu trình ứng dụng (App Lifecycle) chạy trên iOS.

3. Điều kiện tiên quyết (Prerequisite)

• Bài viết trước: Đã qua Khai báo ứng dụng & Lấy thông tin tích hợp.
• Dữ liệu đầu vào: Lấy các thông số MerchantID, ConnectorID, URL API và gói thư mục MobioSDK.xcframework đã download.
• Yêu cầu cấu hình hệ thống: Dự án hoạt động với phiên bản iOS 10.0 trở lên. Ngôn ngữ Swift 5.0 hoặc cao hơn. Công cụ lập trình Xcode 12+.

4. Các bước thực hiện

4.1 Thêm gói SDK Core vào Target Application

• Mở App trên Xcode của dự án iOS (Ví dụ: tên project Mobio).
• Chọn khu vực Target. Bấm chọn tên Project của bạn.
• Mở tab thiết lập General.
• Cuộn xuống khu vực Frameworks, Libraries, and Embedded Content.

• Chọn Add Item (+).

• Từ Menu sổ ra, cuộn xuống, chọn Add File → Mở cửa sổ thư mục chứa Bundle SDK tải về.

• Chọn tệp mã nguồn MobioSDK.xcframework → Bấm Open.
• Sau khi add vào danh sách, đảm bảo cột Embed đã chuyển đổi sang Setup, chọn thiết lập: Embed & Sign.

4.2 Thêm quyền vào file Info.plist (Bắt buộc)

Bối cảnh

MobioSDK sử dụng App Tracking Transparency (ATT) framework của Apple để yêu cầu quyền truy cập IDFA (Identifier for Advertisers) – định danh thiết bị dùng cho mục đích phân tích và cá nhân hóa.

Theo chính sách của Apple, kể từ iOS 14, mọi ứng dụng gọi ATTrackingManager.requestTrackingAuthorization đều bắt buộc phải khai báo key NSUserTrackingUsageDescription trong file Info.plist. Nếu thiếu key này:

• iOS 14.x: App sẽ crash ngay lập tức khi SDK khởi tạo.
• iOS 15+: App không crash — hệ thống tự động từ chối quyền mà không hiển thị dialog, nhưng Apple vẫn yêu cầu key này khi submit lên App Store.

Thực hiện

• Mở file hệ thống cấu hình Info.plist trong nhánh Root Xcode Project.
• Khai báo 1 Key cấu hình tracking ID tên là: NSUserTrackingUsageDescription.

<key>NSUserTrackingUsageDescription</key>
<string>Ứng dụng sử dụng thông tin này để cá nhân hóa quảng cáo và phân tích hành vi người dùng.</string>

Lưu ý: Nội dung chuỗi mô tả có thể tùy chỉnh theo ngữ cảnh ứng dụng, nhưng cần giải thích rõ mục đích sử dụng dữ liệu tracking. Apple có thể từ chối app nếu mô tả quá chung chung hoặc không chính xác.

4.3 Khởi tạo SDK (InitSDK AppDelegate)

Lưu ý quan trọng: Quá trình khởi tạo SDK (Init) KHÔNG tự động diễn ra. Developer bắt buộc phải tự tay viết code gọi hàm khởi tạo ngay khi ứng dụng vừa bật lên. Chỉ sau khi gọi lệnh này thành công, SDK mới bắt đầu tự động sinh Profile ẩn danh chạy ngầm.

• Mở file AppDelegate.swift của dự án
• Import MobioSDK vào header

import MobioSDK

• Khởi tạo Mobio SDK

import UIKit
import CoreData
import MobioSDK

@mainclass AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate {
          
     func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
          
          Mobio.shared.initWithLaunchOptions(merchantId: "MERCHANT_ID", connectorId: "CONNECTOR_ID", apiUrl: "API_URL", source: "SOURCE")
          returntrue
     }
}

Lưu ý:

• Thay tham số MerchantID, ConnectorID và API_URL lấy từ Bước Khai báo ứng dụng & Lấy thông tin tích hợp.
• Đổi thông tin source (không bắt buộc): dùng để ghi nhận nguồn dữ liệu cho profile, sau này sẽ phân định Profile trên Mobio đến từ nguồn nào, giá trị mặc định là App.

5. Quy tắc vận hành

• Sau khi khởi tạo SDK với hàm init , mỗi khi một người dùng truy cập app lần đầu, Mobio SDK sẽ tự khởi tạo một profile ẩn danh mới. Tất cả hành vi tương tác sau đó của khách hàng mà chưa có thông tin định danh sẽ được gộp vào Profile ẩn danh này.

6. Các câu hỏi thường gặp (FAQ)

Chưa có thông tin cho mục này

7. Bước tiếp theo

Cấu hình Target Notification Extension nhận Rich Push iOS nếu bạn muốn cấu hình Rich Notification để gửi push out app, hoặc

Gắn Event Tracking vào ứng dụng iOS nếu không cần push out app.