Tổng Quan Deep Link
Bạn sẽ học: Deep Link là gì, sự khác nhau giữa hai cơ chế immediate và deferred, luồng hoạt động end-to-end, và những thứ bạn cần chuẩn bị trước khi tích hợp vào ứng dụng iOS/Android.
Beta: Deep Link Attribution hiện đang ở giai đoạn Beta và yêu cầu gói Pro để xem phần analytics. Phần cấu hình domain và file xác minh khả dụng cho mọi gói. API và payload mô tả ở đây có thể thay đổi trong các bản cập nhật tới.
Deep Link là gì?
Deep Link cho phép một short link hoặc QR code của Li2 mở thẳng ứng dụng di động của bạn thay vì mở trình duyệt, khi người dùng đã cài app trên thiết bị. Nếu họ chưa cài app, Li2 vẫn ghi nhận lượt chạm để ứng dụng có thể khôi phục đúng nội dung ngay trong lần mở đầu tiên sau khi cài đặt. Li2 cung cấp Li2 SDK chính thức cho iOS (Swift Package, iOS 15+). Với Android hoặc khi cần tùy biến sâu, bạn tích hợp trực tiếp qua HTTP API (POST /api/v1/track/open).
Hai cơ chế hoạt động
Immediate (Đã cài app)
Người dùng đã cài app, chạm vào link → hệ điều hành mở thẳng app qua Universal Link (iOS) hoặc App Link (Android). App gọi
/track/open với deepLink để ghi nhận và điều hướng.Deferred (Chưa cài app)
Người dùng chưa cài app, chạm vào link → tải app từ store → lần mở đầu tiên app khôi phục link gốc qua clipboard (iOS) hoặc Google Play Install Referrer (Android).
Luồng hoạt động end-to-end
Người dùng chạm vào short link trên thiết bị di động
Link nằm trên một custom domain đã bật Deep Link. Hệ điều hành đọc file
.well-known của domain để biết app nào được phép xử lý link đó.Hệ điều hành quyết định mở app hay không
- Đã cài app → mở thẳng app (Universal Link / App Link). Đây là luồng immediate.
- Chưa cài app → hiển thị trang web hoặc chuyển tới App Store / Play Store.
Trường hợp chưa cài: app khôi phục link sau khi cài
Trong lần mở đầu tiên, app đọc tín hiệu deferred:
- iOS: đọc clipboard, tìm tham số
li2_cidtrong link đã sao chép. - Android: gọi Google Play Install Referrer, giải mã tham số
li2_dl.
App gọi POST /track/open
App gửi tín hiệu (
deepLink, installReferrer, hoặc clipboardStatus) kèm publishable key trong header X-Li2-Key. Server đối chiếu và trả về link.url đích cùng matchMethod.Ba định danh bạn sẽ gặp
Luồng deferred đi qua vài định danh khác nhau — phân biệt rõ để không nhầm khi ghép code:| Định danh | Xuất hiện ở đâu | Là gì | Ai tạo |
|---|---|---|---|
li2_cid | Trong link trên clipboard (iOS) và bên trong giá trị li2_dl (Android) | Token 16 ký tự base62 định danh cú click gốc; bằng đúng visits.li2_cid để nối lượt cài về click | Li2 sinh phía server |
li2_dl | Tham số trong Google Play Install Referrer (Android) | “Bao” chứa URL đích đã URL-encode (gồm cả li2_cid) mà Li2 ghép vào referrer khi chuyển tới Play Store | Li2 sinh phía server |
clickId | Trường trong response /track/open | Id của click khi khớp (bằng li2_cid), hoặc id ngẫu nhiên khi trượt | Server trả về |
Bạn không tự tạo các định danh này. Li2 gieo chúng ở phía hạ tầng: trang trung gian (chỉ phục vụ khi chưa cài app) chép link kèm
li2_cid vào clipboard, và bản chuyển hướng tới Play Store ghép sẵn li2_dl vào referrer. Phía app, bạn chỉ đọc rồi gửi nguyên trạng cho /track/open.Yêu cầu trước khi tích hợp
Custom Domain đã xác minh
Bắt buộc dùng domain riêng đã verify. Subdomain miễn phí
*.li2.link không dùng được cho Deep Link vì là hạ tầng dùng chung.Cấu hình App trên Dashboard
Đăng ký iOS (Team ID + Bundle ID) và/hoặc Android (package name + SHA-256) để Li2 sinh file xác minh. Xem Cấu Hình Domain.
Publishable Key
Key dạng
li2_pk_... gửi qua header X-Li2-Key. Lấy tại Settings → Analytics → Publishable Key trong dashboard (xem Thiết lập Conversion Tracking nếu chưa bật Analytics). Không dùng server API key (X-Li2-API-Key) cho endpoint này.Gói Pro (cho Analytics)
Cấu hình deep link miễn phí, nhưng trang Deep Link Analytics yêu cầu gói Pro.
Lộ trình tích hợp
Ba bước, theo đúng thứ tự:Cấu hình domain & file xác minh
Đăng ký app trên dashboard và để Li2 phục vụ
apple-app-site-association + assetlinks.json cho custom domain. → Cấu Hình DomainKhai báo native & gọi /track/open
Thêm Associated Domains (iOS) / intent-filter
autoVerify (Android), rồi gọi POST /track/open cho cả luồng immediate lẫn deferred. → Tích Hợp iOS & AndroidTra cứu hợp đồng API
Đối chiếu request/response,
matchMethod, missReason và mã trạng thái khi cần. → API: POST /track/openBước tiếp theo
Cấu Hình Domain & File Xác Minh
Đăng ký app và để Li2 phục vụ
apple-app-site-association + assetlinks.json.Tích Hợp iOS & Android
Các bước cài đặt native cho từng nền tảng, kèm payload mẫu.
API: POST /track/open
Hợp đồng API đầy đủ: request, response, matchMethod, missReason.
Hướng dẫn cho người dùng
Góc nhìn marketer: cấu hình và đọc analytics trên dashboard.