Cách chuyển tham số theo dõi từ Web sang cài đặt ứng dụng

Làm thế nào để chuyển tham số theo dõi từ trang web di động sang cài đặt trên cửa hàng ứng dụng? Việc chuyển tham số theo dõi từ trang web di động sang ứng dụng vừa cài đặt yêu cầu tải Web JS SDK của OpoInstall, thu thập các tham số URL trong danh sách cho phép và khôi phục dữ liệu phân bổ được hỗ trợ thông qua native SDK khi ứng dụng khởi chạy lần đầu tiên.

Ghép nối tham số thông qua tải xuống từ cửa hàng ứng dụng là quá trình bảo toàn các tham số URL web hợp lệ khi người dùng chuyển từ trang đích di động sang cửa hàng ứng dụng và sau đó khởi chạy ứng dụng vừa cài đặt. Web SDK sẽ thu thập ngữ cảnh chiến dịch hoặc giới thiệu, trong khi cơ chế hỗ trợ của nền tảng hoặc dịch vụ khôi phục trì hoãn sẽ cung cấp các tham số liên quan cho ứng dụng native. Việc khôi phục phụ thuộc vào nền tảng, cấu hình SDK, tín hiệu khớp khả dụng và các yêu cầu về quyền riêng tư áp dụng.

Khoảng cách phân bổ Web-to-Store: Rào cản nền tảng trên các cửa hàng ứng dụng

Rào cản ngắt kết nối: Cách sandbox hệ điều hành cô lập ngữ cảnh trình duyệt

Phân tích web thường sử dụng chuỗi truy vấn URL, bao gồm thẻ UTM (utm_source, utm_medium, utm_campaign), mã định danh lượt nhấp quảng cáo như gclid và fbclid, và các tham số giới thiệu tùy chỉnh.

Trong một trang web tham gia, các API trình duyệt và hệ thống phân tích bên thứ nhất có thể thu thập các giá trị này cho các luồng công việc phân tích và chiến dịch được cho phép.

Thử thách xuất hiện khi khách truy cập rời trình duyệt và bắt đầu quá trình cài đặt ứng dụng trên cửa hàng. Trình duyệt và ứng dụng native vừa cài đặt hoạt động trong các môi trường riêng biệt. Cookie trình duyệt, bộ nhớ phiên (session storage) và tham số URL trang web không tự động xuất hiện bên trong ứng dụng sau khi cài đặt.

Do đó, các nhà phát triển cần một cơ chế giới thiệu được cửa hàng hỗ trợ hoặc quy trình khôi phục tham số trì hoãn để kết nối ngữ cảnh tiền cài đặt hợp lệ với phiên ứng dụng sau cài đặt.

Đặc thù nền tảng: So sánh Apple App Store và Google Play Store

Các cửa hàng ứng dụng di động hỗ trợ những phương thức khác nhau để chuyển ngữ cảnh giới thiệu.

• Apple App Store (iOS): Việc cài đặt App Store tiêu chuẩn không tự động chuyển tiếp các chuỗi truy vấn URL bên ngoài tùy ý vào môi trường khởi chạy lần đầu của ứng dụng vừa cài đặt. Các dịch vụ khôi phục trì hoãn hoặc quy trình do người dùng điều phối có thể giúp khôi phục ngữ cảnh hợp lệ, tùy thuộc vào yêu cầu quyền riêng tư của Apple.
• Google Play Store (Android): Google cung cấp API Google Play Install Referrer chính thức. Khi sử dụng luồng giới thiệu Google Play được xây dựng đúng cách, ứng dụng đã cài đặt có thể truy xuất siêu dữ liệu giới thiệu hỗ trợ, bao gồm chuỗi giới thiệu và dấu thời gian liên quan.

Các cơ chế này không nên được coi là có thể hoán đổi cho nhau. Google Play cung cấp giao diện giới thiệu cấp cửa hàng chính thức, trong khi việc khôi phục tham số trì hoãn tùy ý trên iOS yêu cầu một cơ chế được thiết kế riêng và tuân thủ chính sách.

Tác động kinh doanh của lưu lượng cài đặt không được phân bổ đến việc tính toán ROI kênh

Nếu các tham số chiến dịch bị mất giữa lượt truy cập web và quá trình cài đặt ứng dụng, các hệ thống phân tích có thể không liên kết chính xác lượt cài đặt với chiến dịch gốc của nó.

Điều này dẫn đến các lượt cài đặt không xác định được nguồn gốc, báo cáo thu hút người dùng không đầy đủ và tính toán sai lệch về Lợi tức đầu tư (ROI) hoặc Chi phí thu hút khách hàng (CAC).

Việc mất tham số cũng có thể ảnh hưởng đến trải nghiệm giới thiệu. Ví dụ, một liên kết giới thiệu web có thể bao gồm mã định danh người mời hoặc mã khuyến mãi:

https://example.com/download?inviter_id=USR_1024
https://example.com/download?promo_code=WELCOME50

Nếu ứng dụng không thể khôi phục các giá trị này, người dùng có thể phải nhập lại theo cách thủ công.

Tuy nhiên, việc khôi phục giá trị giới thiệu hoặc mã khuyến mãi không tự động cho phép nhận phần thưởng. Phụ trợ (backend) ứng dụng phải xác minh độc lập tính đủ điều kiện, giới hạn đổi thưởng và các quy tắc kinh doanh áp dụng.

Cơ chế hỗ trợ từ cửa hàng so với khôi phục tham số trì hoãn: Apple App Store và Google Play

Cơ chế Google Play Store: Tận dụng API Native Install Referrer

Trên Android, API Google Play Install Referrer cung cấp một cơ chế chính thức để truy xuất siêu dữ liệu giới thiệu cài đặt được hỗ trợ.

URL tải xuống Google Play có thể bao gồm tham số referrer đã mã hóa:

https://play.google.com/store/apps/details?id=com.example.app&referrer=utm_source%3Dfacebook%26inviter_id%3DUSR_1024

Trong URL minh họa này, giá trị referrer đã mã hóa đại diện cho:

utm_source=facebook&inviter_id=USR_1024

Sau khi cài đặt, một ứng dụng Android native có thể sử dụng Install Referrer Client để truy xuất thông tin giới thiệu có sẵn từ Google Play.

Việc liệu một phiên bản cụ thể của OpoInstall Web SDK có tự động tạo, sửa đổi hoặc quản lý URL như vậy hay không cần được xác minh dựa trên tài liệu và hành vi triển khai của nó. Sự tồn tại của API chính thức từ Google không thiết lập cách triển khai nội bộ của SDK bên thứ ba.

Ranh giới Apple App Store: Xử lý chuyển hướng cửa hàng tiêu chuẩn mà không có tham số truy vấn native

Apple App Store không chuyển trực tiếp các tham số truy vấn web tùy ý vào callback khởi chạy lần đầu của ứng dụng vừa cài đặt.

Do đó, một quy trình khôi phục trì hoãn có thể liên quan đến việc thu thập thông tin chiến dịch được phép trước khi chuyển hướng cửa hàng và yêu cầu ngữ cảnh liên quan khi ứng dụng native khởi chạy.

Đối với quy trình dựa trên SDK, các nhà phát triển phải phân biệt giữa chức năng mà nhà cung cấp ghi lại và các phương thức khớp được sử dụng bởi phiên bản SDK đã triển khai.

Bất kỳ phương thức khớp hoặc thu thập dữ liệu nào cũng phải tuân thủ các chính sách quyền riêng tư của Apple. Cụ thể, việc triển khai phân bổ không được dựa vào lấy dấu thiết bị (fingerprinting) bị cấm hoặc giả định rằng quyền ATT (App Tracking Transparency) làm cho một phương thức khớp vốn bị cấm trở nên chấp nhận được.

Universal Links hữu ích để định tuyến các liên kết được hỗ trợ vào một ứng dụng đã cài đặt, nhưng bản thân chúng không đảm bảo rằng các tham số truy vấn web tùy ý sẽ tồn tại sau một quá trình cài đặt App Store mới.

Sự khác biệt về kiến trúc đa nền tảng: Xây dựng hợp đồng tham số thống nhất

Mặc dù Android và iOS sử dụng các cơ chế nền tảng khác nhau, ứng dụng có thể chuẩn hóa các giá trị được khôi phục thành một lược đồ cấp ứng dụng được chia sẻ.

Ví dụ:

{
  "utm_source": "facebook",
  "utm_medium": "paid_social",
  "utm_campaign": "summer_sale",
  "inviter_id": "USR_1024",
  "promo_code": "WELCOME50"
}

Đối tượng JSON này đại diện cho một hợp đồng tham số được chuẩn hóa do ứng dụng định nghĩa, không phải là định dạng phản hồi nghĩa đen được đảm bảo từ mọi bản phát hành của SDK OpoInstall.

Ứng dụng nên tách các trường này thành hai loại:

• Phân bổ tiếp thị (Marketing attribution): utm_source, utm_medium và utm_campaign.
• Hành động giới thiệu và khuyến mãi: inviter_id và promo_code.

Phân bổ tiếp thị có thể được gửi đến một quy trình phân tích được ủy quyền. Các hành động giới thiệu và khuyến mãi yêu cầu xác thực độc lập từ phía máy chủ trước khi ứng dụng cấp bất kỳ lợi ích nào.

Vai trò của việc lưu trữ ngữ cảnh (Contextual Payload Caching) trong việc thu hẹp chuyển hướng cửa hàng

Các dịch vụ khôi phục trì hoãn thường yêu cầu một khoảng thời gian lưu giữ hạn chế cho ngữ cảnh cài đặt.

Cửa sổ lưu giữ áp dụng, hành vi khôi phục và khả năng khớp phụ thuộc vào dịch vụ được triển khai, cấu hình SDK, điều kiện mạng, giới hạn nền tảng và các yêu cầu về quyền riêng tư.

Các nhóm kỹ thuật nên đo lường kết quả khôi phục bằng cách sử dụng chính các nhóm cài đặt của riêng họ thay vì áp dụng các tuyên bố về độ chính xác không được hỗ trợ.

Kiến trúc ngữ cảnh trì hoãn chú trọng quyền riêng tư và ranh giới nền tảng

Ranh giới Clipboard hệ thống trên iOS: Biểu ngữ minh bạch và cơ chế ý định UIPasteControl

Một số phương thức liên kết trì hoãn trong quá khứ đã sử dụng clipboard của hệ thống để mang ngữ cảnh tạm thời giữa các ứng dụng.

Tuy nhiên, iOS hạn chế và công khai quyền truy cập clipboard giữa các ứng dụng cho người dùng.

• iOS 14: Việc đọc nội dung được sao chép từ một ứng dụng khác có thể kích hoạt thông báo truy cập clipboard.
• iOS 16 trở lên: Một số thao tác dán theo chương trình có thể kích hoạt yêu cầu quyền. Các điều khiển như UIPasteControl hỗ trợ các tương tác dán do người dùng khởi tạo.

Do đó, quyền truy cập clipboard nói chung không được coi là kênh vận chuyển tham số cài đặt vô hình hoặc không hạn chế.

Các ứng dụng sử dụng chức năng liên quan đến clipboard nên đảm bảo sự tương tác phù hợp với kỳ vọng của người dùng và xử lý việc từ chối quyền hoặc nội dung bị thiếu một cách khéo léo.

Hạn chế Clipboard nền trước của Android: Ràng buộc điều hướng và tự động xóa

Android cũng áp dụng các hạn chế đối với quyền truy cập clipboard.

• Android 10 trở lên: Quyền truy cập clipboard bị hạn chế đối với các ứng dụng không ở ngữ cảnh nền trước, tuân theo các ngoại lệ do nền tảng xác định.
• Android 13 trở lên: Android cung cấp phản hồi giao diện người dùng liên quan đến clipboard và hành vi tự động xóa nội dung clipboard.

Các ứng dụng không được giả định rằng dữ liệu clipboard có thể được truy xuất một cách âm thầm hoặc vẫn khả dụng vô thời hạn.

Quyền truy cập clipboard nên là tùy chọn và chỉ giới hạn trong các luồng công việc phù hợp với người dùng thay vì đóng vai trò là kênh phân bổ chính được giả định.

Tuân thủ nghiêm ngặt chính sách quyền riêng tư của người dùng Apple và chính sách sử dụng dữ liệu: Cấm lấy dấu thiết bị

Apple cấm lấy dấu thiết bị (device fingerprinting) được sử dụng để nhận dạng người dùng hoặc thiết bị thông qua sự kết hợp các đặc điểm của thiết bị và môi trường.

Việc triển khai không được xây dựng các mã định danh bền vững hoặc xác suất từ sự kết hợp của địa chỉ IP, thông tin tác nhân người dùng (user agent), đặc điểm hiển thị hoặc các tín hiệu thiết bị khác vi phạm chính sách của Apple.

Việc cấp quyền App Tracking Transparency không làm cho các phương thức lấy dấu bị cấm trở nên hợp lệ.

Đối với bất kỳ dịch vụ khôi phục tham số trì hoãn bên thứ ba nào, nhà phát triển nên xem xét việc thu thập dữ liệu thực tế, hành vi khớp, công bố quyền riêng tư và các yêu cầu chính sách nền tảng của SDK được triển khai.

Việc tích hợp chú trọng quyền riêng tư nên ưu tiên giảm thiểu dữ liệu, tương tác minh bạch với người dùng và các cơ chế nền tảng được hỗ trợ.

Ranh giới Bảo mật và Tin cậy: Quản lý vòng đời tham số và ủy quyền máy chủ

Tất cả các tham số được khôi phục phải được coi là đầu vào không đáng tin cậy.

Thẻ tiếp thị và mã thông báo giới thiệu có thể bắt nguồn từ các URL có thể chỉnh sửa hoặc các yêu cầu từ phía khách hàng không đáng tin cậy. Chỉ riêng sự hiện diện của chúng không thiết lập rằng một chiến dịch là hợp pháp hoặc người dùng đủ điều kiện nhận phần thưởng.

Các ứng dụng nên tuân theo các nguyên tắc sau:

• Giá trị trong danh sách cho phép (Allowlisted values): Chỉ chấp nhận các khóa được hỗ trợ rõ ràng và các giá trị có giới hạn.
• Tách biệt phân bổ khỏi ủy quyền: Các giá trị UTM có thể mô tả nguồn gốc lưu lượng; chúng không được tự ý ủy quyền cho các lợi ích khuyến mãi.
• Bản ghi chờ xử lý có giới hạn thời gian: Chỉ giữ lại thông tin cần thiết cho việc xử lý, tuân theo cửa sổ hết hạn do ứng dụng định nghĩa.
• Lưu trữ được bảo vệ: Sử dụng bộ nhớ phù hợp với độ nhạy của các mã thông báo chờ xử lý, chẳng hạn như thiết kế dựa trên Android Keystore hoặc iOS Keychain Services khi cần thiết.
• Kết quả phân phối độc lập: Đối với các bản ghi chứa cả tham số tiếp thị và phần thưởng, ứng dụng phải theo dõi các kết quả bắt buộc một cách độc lập.
• Xác thực phần thưởng phía máy chủ: Tín dụng giới thiệu, giảm giá khuyến mãi và các quyền lợi tương tự phải được phê duyệt bởi một phụ trợ ứng dụng đã xác thực.
• Áp dụng phần thưởng lũy đẳng (Idempotent): Phụ trợ nên thực thi tính lũy đẳng cấp giao dịch và các ràng buộc duy nhất cấp doanh nghiệp để các yêu cầu lặp đi lặp lại từ phía khách hàng không thể sao chép các phần thưởng chỉ áp dụng một lần.

Đoạn mã bên dưới minh họa ranh giới tham số và trách nhiệm tích hợp của ứng dụng chủ. Nó không cố gắng cung cấp một hệ thống lưu trữ, phân tích hoặc giao dịch phần thưởng hoàn chỉnh cấp sản xuất.

Triển khai từ đầu đến cuối: Thu thập tham số Web đến khôi phục Native

Làm sạch tham số truy vấn web: HTML Bootstrap, phân tích danh sách cho phép và thiết lập Web JS SDK

Một trang đích có thể thu thập các tham số truy vấn được hỗ trợ rõ ràng và chuyển chúng tới Web SDK dưới dạng payload giới hạn.

Ví dụ sau đây minh họa:

• Tải SDK từ nguồn được cấu hình.
• Bảo toàn liên kết dự phòng tải xuống HTTPS tiêu chuẩn.
• Chỉ chấp nhận các khóa tham số được hỗ trợ.
• Từ chối các giá trị nằm ngoài chính sách ký tự và độ dài nghiêm ngặt.
• Kết nối hành động tải xuống của SDK với nút tải xuống của trang.

Hàm tạo SDK, các khóa cấu hình và các phương thức là mang tính đại diện. Hãy xác minh chữ ký của chúng so với bản phát hành Web SDK OpoInstall chính xác trước khi xuất bản hoặc triển khai.

<!-- CODE_BLOCK_01: Representative HTML Bootstrap and Web SDK Integration -->
<!-- File: landing_page.html -->

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Application Download</title>
</head>
<body>
    <!-- Thay thế bằng URL tải xuống HTTPS hoặc URL định tuyến cửa hàng thực tế. -->
    <a
        id="download-app-btn"
        href="https://app.example.com/store-download"
    >
        Tải xuống ứng dụng
    </a>

    <!-- Xác minh URL CDN chính thức so với phiên bản SDK đã triển khai. -->
    <script src="https://web.cdn.opoinstallcloud.com/openinstall.js"></script>

    <script>
    (function () {
        "use strict";

        function getSanitizedQueryParams() {
            var allowedKeys = new Set([
                "utm_source",
                "utm_medium",
                "utm_campaign",
                "inviter_id",
                "promo_code"
            ]);

            var validPattern = /^[A-Za-z0-9_.-]{1,64}$/;
            var result = Object.create(null);

            try {
                var query = new URLSearchParams(window.location.search);

                query.forEach(function (value, key) {
                    if (
                        allowedKeys.has(key) &&
                        validPattern.test(value) &&
                        !Object.prototype.hasOwnProperty.call(result, key)
                    ) {
                        result[key] = value;
                    }
                });
            } catch (error) {
                console.warn("Không thể phân tích các tham số URL.");
                return Object.create(null);
            }

            return result;
        }

        var downloadButton = document.getElementById(
            "download-app-btn"
        );

        // Giữ href của neo làm dự phòng trình duyệt thông thường.
        if (!downloadButton) {
            return;
        }

        if (typeof OpenInstall === "undefined") {
            console.warn(
                "Web SDK không khả dụng; sử dụng liên kết tải xuống."
            );
            return;
        }

        var customParams = getSanitizedQueryParams();

        try {
            new OpenInstall({
                appKey: "OPOINSTALL_APPKEY_PLACEHOLDER",
                data: customParams,

                onready: function () {
                    var sdkClient = this;

                    downloadButton.addEventListener(
                        "click",
                        function (event) {
                            try {
                                // Phương thức SDK đại diện.
                                // Xác minh hành vi và xử lý lỗi không đồng bộ
                                // cho bản phát hành được triển khai.
                                sdkClient.wakeupOrInstall();
                                event.preventDefault();
                            } catch (error) {
                                console.warn(
                                    "Hành động SDK thất bại; trình duyệt sẽ sử dụng dự phòng."
                                );

                                // Không ngăn chặn hành động neo mặc định.
                            }
                        }
                    );
                }
            });
        } catch (error) {
            console.warn(
                "Khởi tạo Web SDK thất bại; sử dụng liên kết dự phòng."
            );
        }
    })();
    </script>
</body>
</html>

Chính sách giá trị cố ý chỉ chấp nhận chữ cái, chữ số, dấu gạch dưới, dấu gạch ngang và dấu chấm, tối đa 64 ký tự.

Các giá trị chứa dấu cách hoặc các ký tự khác bị loại trừ trong quá trình triển khai tham chiếu này. Các nhóm có yêu cầu đặt tên UTM rộng hơn nên xác định và kiểm tra lược đồ cụ thể cho từng trường thay vì âm thầm giả định rằng tất cả các giá trị URL đều được hỗ trợ.

Tương tự, các mã định danh lượt nhấp quảng cáo như gclid và fbclid được thảo luận như các khái niệm phân bổ web phổ biến nhưng không được bao gồm trong danh sách cho phép mẫu này. Việc hỗ trợ chúng đòi hỏi một bộ sưu tập dữ liệu, quy trình lưu giữ và đánh giá quyền riêng tư riêng biệt.

Neo dự phòng vẫn khả dụng khi SDK không tải hoặc không thể khởi tạo. Vì các hoạt động của SDK có thể thất bại không đồng bộ, việc tích hợp sản xuất phải tuân theo các hành vi xử lý lỗi và chuyển hướng đã ghi lại của SDK; một try/catch đồng bộ đơn thuần không phải là chiến lược dự phòng không đồng bộ hoàn chỉnh.

Triển khai Native Android: Thiết lập SDK, xác thực tham số và hợp đồng ứng dụng chủ

Sau khi cài đặt, ứng dụng Android có thể yêu cầu các tham số được hỗ trợ từ native SDK và chuẩn hóa chúng thành một bản ghi do ứng dụng định nghĩa.

Mẫu bên dưới cố ý giữ các trách nhiệm tách biệt:

1. SDK OpoInstall khởi tạo trong quy trình chính của ứng dụng.
2. Callback native cung cấp một payload ứng viên.
3. Ứng dụng xác thực và chuẩn hóa payload.
4. Ứng dụng lưu bản ghi thông qua giao diện lưu trữ do ứng dụng chủ cung cấp.
5. Một thành phần xử lý do ứng dụng chủ cung cấp điều phối phân bổ tiếp thị và ủy quyền phần thưởng.
6. Ứng dụng chỉ đánh dấu bản ghi là hoàn tất sau khi thành phần đó báo cáo kết quả xử lý đã xác minh.

Quan trọng: Các giao diện máy chủ là hợp đồng do ứng dụng định nghĩa, không phải API của OpoInstall. Ví dụ này yêu cầu ứng dụng chủ phải cung cấp các bản triển khai. Nó không bao gồm lưu trữ dự phòng không an toàn, gửi phân tích mô phỏng hoặc phản hồi ủy quyền phần thưởng giả lập.

// CODE_BLOCK_02: Representative Android Integration (Kotlin)
// File: CustomApplication.kt and MainActivity.kt
//
// Xác minh các tệp nhập (imports) và callbacks OpoInstall so với tệp AAR đã triển khai.
// Các bản triển khai của máy chủ phải được cung cấp trước khi xử lý tham số.

package com.example.app

import android.app.ActivityManager
import android.app.Application
import android.content.Context
import android.os.Bundle
import android.os.Handler
import android.os.Looper
import android.os.Process
import android.util.Log
import androidx.appcompat.app.AppCompatActivity
import com.opoinstall.api.OpoInstall
import com.opoinstall.api.OpoData
import com.opoinstall.api.OpoError
import com.opoinstall.api.ResultCallBack
import org.json.JSONObject
import java.util.UUID

enum class ParamFetchState {
    NOT_STARTED,
    FETCHING,
    RECEIVED,
    APPLIED,
    REJECTED,
    NO_MATCH,
    RETRYABLE_FAILURE
}

data class PendingAttributionRecord(
    val utmSource: String?,
    val utmMedium: String?,
    val utmCampaign: String?,
    val inviterId: String?,
    val promoCode: String?,
    val idempotencyKey: String,
    val createdAt: Long,
    val expiresAt: Long
) {
    val hasAttributionData: Boolean
        get() = listOf(
            utmSource, utmMedium, utmCampaign
        ).any { !it.isNullOrEmpty() }

    val hasRewardData: Boolean
        get() = !inviterId.isNullOrEmpty() ||
                !promoCode.isNullOrEmpty()

    val hasAnyData: Boolean
        get() = hasAttributionData || hasRewardData

    fun isValid(): Boolean {
        val now = System.currentTimeMillis()
        val pattern = Regex("^[A-Za-z0-9_.-]{1,64}$")

        val values = listOf(
            utmSource, utmMedium, utmCampaign,
            inviterId, promoCode
        )

        val validFields = values.all {
            it == null || pattern.matches(it)
        }

        val validWindow =
            expiresAt > createdAt &&
            expiresAt - createdAt <= 48L * 60 * 60 * 1000 &&
            now >= createdAt &&
            now <= expiresAt

        val validId = try {
            UUID.fromString(idempotencyKey)
            true
        } catch (_: IllegalArgumentException) {
            false
        }

        return hasAnyData &&
               validFields &&
               validWindow &&
               validId
    }
}

// Hợp đồng lưu trữ bảo mật do máy chủ định nghĩa.
// Việc triển khai phải phân biệt dữ liệu bị thiếu với
// lỗi lưu trữ và xử lý việc liên kết tài khoản khi cần.
interface PendingTransactionStore {
    fun save(record: PendingAttributionRecord): Boolean
    fun load(): PendingAttributionRecord?
    fun clear(): Boolean
}

// Điều phối viên do máy chủ định nghĩa. Việc triển khai của nó chịu trách nhiệm
// cho các xác nhận từ xa/phần thưởng độc lập,
// tính lũy đẳng, xử lý thử lại và kiểm tra danh tính giao dịch.
interface InstallParameterProcessor {
    fun process(
        record: PendingAttributionRecord,
        onComplete: (ProcessingOutcome) -> Unit
    )
}

enum class ProcessingOutcome {
    COMPLETED,
    REJECTED,
    RETRYABLE_FAILURE
}

// Đây là các phần phụ thuộc ứng dụng, KHÔNG PHẢI API SDK OpoInstall.
object HostAppDependencies {
    var transactionStore: PendingTransactionStore? = null
    var parameterProcessor: InstallParameterProcessor? = null

    val isConfigured: Boolean
        get() = transactionStore != null &&
                parameterProcessor != null
}

class CustomApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        if (isMainProcess()) {
            OpoInstall.initialize(this)

            // Ứng dụng chủ phải cấu hình các phần phụ thuộc ở đây
            // sử dụng cơ chế DI/bootstrap thực tế của nó.
            //
            // HostAppDependencies.transactionStore =
            //     hostProvidedProtectedStore
            //
            // HostAppDependencies.parameterProcessor =
            //     hostProvidedInstallParameterProcessor
        }
    }

    private fun isMainProcess(): Boolean {
        val manager = getSystemService(
            Context.ACTIVITY_SERVICE
        ) as ActivityManager

        val currentPid = Process.myPid()

        return manager.runningAppProcesses?.any {
            it.pid == currentPid &&
            it.processName == packageName
        } == true
    }
}

class MainActivity : AppCompatActivity() {

    private val mainHandler = Handler(Looper.getMainLooper())

    private var state = ParamFetchState.NOT_STARTED
    private var activeRecord: PendingAttributionRecord? = null
    private var processingInFlight = false

    private val transactionTtlMs =
        24L * 60 * 60 * 1000

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        startParameterFlow()
    }

    private fun startParameterFlow() {
        val store = HostAppDependencies.transactionStore
        val processor = HostAppDependencies.parameterProcessor

        if (store == null || processor == null) {
            Log.w(
                "OpoInstall",
                "Các phần phụ thuộc máy chủ không khả dụng; quá trình xử lý bị tạm dừng"
            )
            state = ParamFetchState.RETRYABLE_FAILURE
            return
        }

        // Khôi phục bản ghi đại diện.
        // Lưu trữ sản xuất phải báo cáo lỗi đọc riêng biệt
        // từ việc xác nhận không có bản ghi chờ xử lý.
        val existingRecord = try {
            store.load()
        } catch (error: Exception) {
            state = ParamFetchState.RETRYABLE_FAILURE
            return
        }

        if (existingRecord != null) {
            if (existingRecord.isValid()) {
                activeRecord = existingRecord
                state = ParamFetchState.RECEIVED
                processRecord(existingRecord)
            } else {
                // Các bản ghi không hợp lệ hoặc đã hết hạn sẽ không được xử lý.
                if (!store.clear()) {
                    state = ParamFetchState.RETRYABLE_FAILURE
                    return
                }

                requestInstallParameters()
            }
        } else {
            requestInstallParameters()
        }
    }

    private fun requestInstallParameters() {
        if (!HostAppDependencies.isConfigured) {
            state = ParamFetchState.RETRYABLE_FAILURE
            return
        }

        if (state == ParamFetchState.FETCHING ||
            state == ParamFetchState.APPLIED ||
            state == ParamFetchState.NO_MATCH ||
            processingInFlight
        ) {
            return
        }

        state = ParamFetchState.FETCHING

        // Callback SDK đại diện.
        // Xác minh chữ ký so với tệp AAR đã triển khai.
        OpoInstall.getInstance().getInstallParam(
            object : ResultCallBack<OpoData> {

                override fun onResult(opoData: OpoData?) {
                    mainHandler.post {
                        if (state != ParamFetchState.FETCHING) {
                            return@post
                        }

                        val rawData: Any? = opoData?.data

                        val payload = when (rawData) {
                            is String -> rawData
                            is JSONObject -> rawData.toString()
                            is Map<*, *> -> try {
                                JSONObject(rawData).toString()
                            } catch (_: Exception) {
                                null
                            }
                            else -> null
                        }

                        val record = payload?.let {
                            parseAndSanitizeRawPayload(it)
                        }

                        if (record == null) {
                            // Không có dữ liệu hợp lệ nào được khôi phục.
                            // Điều này không thiết lập một lượt cài đặt hữu cơ.
                            state = ParamFetchState.NO_MATCH
                            return@post
                        }

                        val store =
                            HostAppDependencies.transactionStore

                        if (store == null ||
                            !HostAppDependencies.isConfigured
                        ) {
                            state = ParamFetchState.RETRYABLE_FAILURE
                            return@post
                        }

                        activeRecord = record

                        // Không yêu cầu khôi phục bền vững nếu lưu thất bại.
                        val saved = try {
                            store.save(record)
                        } catch (_: Exception) {
                            false
                        }

                        if (!saved) {
                            Log.w(
                                "OpoInstall",
                                "Bản ghi chờ xử lý không thể được lưu trữ"
                            )
                            state = ParamFetchState.RETRYABLE_FAILURE
                            return@post
                        }

                        state = ParamFetchState.RECEIVED
                        processRecord(record)
                    }
                }

                override fun onError(error: OpoError?) {
                    mainHandler.post {
                        if (state == ParamFetchState.FETCHING) {
                            Log.w(
                                "OpoInstall",
                                "Truy xuất tham số cài đặt thất bại"
                            )
                            state = ParamFetchState.RETRYABLE_FAILURE
                        }
                    }
                }
            }
        )
    }

    private fun parseAndSanitizeRawPayload(
        rawJson: String
    ): PendingAttributionRecord? {
        return try {
            if (rawJson.length > 4096) return null

            val json = JSONObject(rawJson)
            val pattern = Regex("^[A-Za-z0-9_.-]{1,64}$")

            fun field(key: String): String? =
                (json.opt(key) as? String)?.takeIf {
                    pattern.matches(it)
                }

            val now = System.currentTimeMillis()

            val record = PendingAttributionRecord(
                utmSource = field("utm_source"),
                utmMedium = field("utm_medium"),
                utmCampaign = field("utm_campaign"),
                inviterId = field("inviter_id"),
                promoCode = field("promo_code"),
                idempotencyKey = UUID.randomUUID().toString(),
                createdAt = now,
                expiresAt = now + transactionTtlMs
            )

            record.takeIf { it.isValid() }
        } catch (_: Exception) {
            null
        }
    }

    private fun processRecord(
        record: PendingAttributionRecord
    ) {
        val processor = HostAppDependencies.parameterProcessor
        val store = HostAppDependencies.transactionStore

        if (processor == null || store == null ||
            !record.isValid()
        ) {
            state = ParamFetchState.RETRYABLE_FAILURE
            return
        }

        if (processingInFlight) return

        processingInFlight = true

        // Bộ xử lý máy chủ không được báo cáo COMPLETED cho đến khi
        // tất cả các kết quả cụ thể theo kênh bắt buộc được xác nhận.
        processor.process(record) { outcome ->
            mainHandler.post {
                // Bỏ qua các giao dịch bị thay thế hoặc cũ.
                if (activeRecord?.idempotencyKey !=
                    record.idempotencyKey
                ) {
                    return@post
                }

                processingInFlight = false

                when (outcome) {
                    ProcessingOutcome.COMPLETED -> {
                        finalizeRecord(
                            record,
                            ParamFetchState.APPLIED
                        )
                    }

                    ProcessingOutcome.REJECTED -> {
                        finalizeRecord(
                            record,
                            ParamFetchState.REJECTED
                        )
                    }

                    ProcessingOutcome.RETRYABLE_FAILURE -> {
                        state =
                            ParamFetchState.RETRYABLE_FAILURE
                    }
                }
            }
        }
    }

    private fun finalizeRecord(
        record: PendingAttributionRecord,
        terminalState: ParamFetchState
    ) {
        val store = HostAppDependencies.transactionStore
            ?: run {
                state = ParamFetchState.RETRYABLE_FAILURE
                return
            }

        if (activeRecord?.idempotencyKey !=
            record.idempotencyKey
        ) {
            return
        }

        // Ví dụ này cố ý để lại việc ghi nhật ký
        // và dọn dẹp nguyên tử cho bộ lưu trữ máy chủ.
        // clear() phải báo cáo xem việc dọn dẹp có thành công hay không.
        val cleared = try {
            store.clear()
        } catch (_: Exception) {
            false
        }

        if (!cleared) {
            state = ParamFetchState.RETRYABLE_FAILURE
            return
        }

        activeRecord = null
        state = terminalState

        Log.i(
            "OpoInstall",
            "Xử lý tham số cài đặt đã được giải quyết"
        )
    }
}

Mẫu Android cố ý không bao gồm bản triển khai mặc định của PendingTransactionStore hoặc InstallParameterProcessor.

Ứng dụng chủ phải cung cấp chúng trước khi gọi quy trình làm việc.

Cụ thể, bộ xử lý không được trả về COMPLETED chỉ vì một câu lệnh ghi nhật ký đã chạy hoặc một yêu cầu không đồng bộ đã được bắt đầu. Kết quả hoàn tất phải tương ứng với các yêu cầu xử lý cho payload thực tế:

• Payload chỉ chứa UTM: Sự kiện phân bổ bắt buộc được hệ thống phân tích đã cấu hình hoặc hàng đợi sự kiện bền vững chấp nhận một cách đáng tin cậy.
• Payload chỉ chứa phần thưởng: Phụ trợ đã xác thực trả về kết quả ủy quyền cuối cùng được chấp nhận.
• Payload hỗn hợp UTM và Phần thưởng: Cả hai kênh bắt buộc đều đạt được các kết quả được định nghĩa độc lập, và một kênh không thể xóa trước công việc cần thiết cho kênh kia.

Nếu ứng dụng chủ yêu cầu khôi phục đa quy trình, bộ xử lý và bộ lưu trữ được bảo vệ phải duy trì đủ tiến trình cụ thể cho từng kênh và bảo toàn các mã định danh giao dịch ổn định.

Hoạt động ở trên minh họa ranh giới tích hợp; nó không thay thế cho các bản triển khai cụ thể của ứng dụng đó.

Triển khai Native iOS: Khôi phục SDK và hợp đồng tích hợp ứng dụng

Việc tích hợp iOS tuân theo cùng ranh giới.

Native SDK cung cấp các tham số cài đặt ứng viên. Ứng dụng xác thực payload, bảo toàn bản ghi chờ xử lý thông qua thành phần lưu trữ do máy chủ cung cấp và ủy quyền xử lý kinh doanh cho một điều phối viên thuộc sở hữu của ứng dụng.

Mã này là đại diện và phải được điều chỉnh cho phù hợp với tên mô-đun, giao thức đại diện (delegate) và chữ ký callback của bản phát hành OpoInstall iOS SDK đã cài đặt.

// CODE_BLOCK_03: Representative iOS Integration (Swift)
// File: AppDelegate.swift
//
// Xác minh mô-đun và các phương thức SDK so với phiên bản khung OpoInstall
// đã triển khai.

import UIKit
import libOpoInstallSDK

enum ParamFetchState: String {
    case notStarted = "NOT_STARTED"
    case fetching = "FETCHING"
    case received = "RECEIVED"
    case applied = "APPLIED"
    case rejected = "REJECTED"
    case noMatch = "NO_MATCH"
    case retryableFailure = "RETRYABLE_FAILURE"
}

struct PendingAttributionRecord: Codable {
    let utmSource: String?
    let utmMedium: String?
    let utmCampaign: String?
    let inviterId: String?
    let promoCode: String?
    let idempotencyKey: String
    let createdAt: TimeInterval
    let expiresAt: TimeInterval

    var hasAttributionData: Bool {
        return [
            utmSource, utmMedium, utmCampaign
        ].contains { !$0.isNilOrEmpty }
    }

    var hasRewardData: Bool {
        return !inviterId.isNilOrEmpty ||
               !promoCode.isNilOrEmpty
    }

    var hasAnyData: Bool {
        return hasAttributionData || hasRewardData
    }

    var isValid: Bool {
        let now = Date().timeIntervalSince1970
        let window = expiresAt - createdAt

        let pattern = "^[A-Za-z0-9_.-]{1,64}$"

        let fields = [
            utmSource, utmMedium, utmCampaign,
            inviterId, promoCode
        ]

        let validFields = fields.allSatisfy { field in
            guard let field = field else { return true }
            return field.range(
                of: pattern,
                options: .regularExpression
            ) != nil
        }

        return hasAnyData &&
               validFields &&
               UUID(uuidString: idempotencyKey) != nil &&
               window > 0 &&
               window <= 48 * 60 * 60 &&
               now >= createdAt &&
               now <= expiresAt
    }
}

private extension Optional where Wrapped == String {
    var isNilOrEmpty: Bool {
        return self?.isEmpty ?? true
    }
}

// Hợp đồng lưu trữ bảo mật do máy chủ cung cấp.
protocol PendingTransactionStore {
    func save(_ record: PendingAttributionRecord) -> Bool
    func load() throws -> PendingAttributionRecord?
    func clear() -> Bool
}

enum ProcessingOutcome {
    case completed
    case rejected
    case retryableFailure
}

// Điều phối viên do máy chủ cung cấp để xử lý phân tích và phần thưởng.
protocol InstallParameterProcessor {
    func process(
        record: PendingAttributionRecord,
        completion: @escaping (ProcessingOutcome) -> Void
    )
}

// Đây là các hợp đồng ứng dụng, không phải API OpoInstall.
struct HostAppDependencies {
    static var transactionStore: PendingTransactionStore?
    static var parameterProcessor: InstallParameterProcessor?

    static var isConfigured: Bool {
        return transactionStore != nil &&
               parameterProcessor != nil
    }
}

@UIApplicationMain
class AppDelegate:
    UIResponder,
    UIApplicationDelegate,
    OpoInstallDelegate {

    var window: UIWindow?

    private var state: ParamFetchState = .notStarted
    private var activeRecord: PendingAttributionRecord?
    private var processingInFlight = false

    private let transactionTTL: TimeInterval =
        24 * 60 * 60

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions:
            [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {

        // Khởi tạo SDK đại diện.
        OpoInstallSDK.initWith(self)

        // Ứng dụng chủ phải đăng ký các phần phụ thuộc thực tế của nó
        // trước khi bắt đầu xử lý tham số.
        //
        // HostAppDependencies.transactionStore =
        //     hostProvidedProtectedStore
        //
        // HostAppDependencies.parameterProcessor =
        //     hostProvidedInstallParameterProcessor

        startParameterFlow()
        return true
    }

    private func startParameterFlow() {
        guard HostAppDependencies.isConfigured,
              let store = HostAppDependencies.transactionStore
        else {
            print(
                "OpoInstall: Các phần phụ thuộc máy chủ bắt buộc không khả dụng"
            )
            state = .retryableFailure
            return
        }

        do {
            if let saved = try store.load() {
                if saved.isValid {
                    activeRecord = saved
                    state = .received
                    processRecord(saved)
                    return
                }

                guard store.clear() else {
                    state = .retryableFailure
                    return
                }
            }
        } catch {
            // Lỗi đọc không tương đương với một cửa hàng trống.
            state = .retryableFailure
            return
        }

        requestInstallParameters()
    }

    private func requestInstallParameters() {
        guard HostAppDependencies.isConfigured,
              state != .fetching,
              state != .applied,
              state != .noMatch,
              !processingInFlight
        else {
            return
        }

        guard let manager = OpoInstallSDK.defaultManager()
        else {
            state = .retryableFailure
            return
        }

        state = .fetching

        // Chữ ký callback đại diện.
        manager.getInstallParmsCompleted({
            [weak self] (appData: OpoinstallData?) in

            DispatchQueue.main.async {
                guard let self = self,
                      self.state == .fetching
                else {
                    return
                }

                let rawData: Any? = appData?.data

                guard let record =
                    self.parseAndSanitizeRawPayload(rawData)
                else {
                    // Không khôi phục được tham số tùy chỉnh hợp lệ.
                    // Đây không phải là bằng chứng xác định về lưu lượng hữu cơ.
                    self.state = .noMatch
                    return
                }

                guard HostAppDependencies.isConfigured,
                      let store =
                          HostAppDependencies.transactionStore
                else {
                    self.state = .retryableFailure
                    return
                }

                self.activeRecord = record

                guard store.save(record) else {
                    // Không yêu cầu bản ghi chờ xử lý bền vững
                    // khi tính bền vững đã thất bại.
                    self.state = .retryableFailure
                    return
                }

                self.state = .received
                self.processRecord(record)
            }
        })
    }

    private func parseAndSanitizeRawPayload(
        _ rawData: Any?
    ) -> PendingAttributionRecord? {

        guard let rawData = rawData else {
            return nil
        }

        var dictionary: [String: Any]?

        if let map = rawData as? [String: Any] {
            dictionary = map
        } else if let jsonString = rawData as? String,
                  jsonString.count <= 4096,
                  let data = jsonString.data(using: .utf8),
                  let parsed = try? JSONSerialization.jsonObject(
                      with: data
                  ) as? [String: Any] {
            dictionary = parsed
        }

        guard let payload = dictionary else {
            return nil
        }

        let pattern = "^[A-Za-z0-9_.-]{1,64}$"

        func field(_ key: String) -> String? {
            guard let value = payload[key] as? String,
                  value.range(
                    of: pattern,
                    options: .regularExpression
                  ) != nil
            else {
                return nil
            }

            return value
        }

        let now = Date().timeIntervalSince1970

        let record = PendingAttributionRecord(
            utmSource: field("utm_source"),
            utmMedium: field("utm_medium"),
            utmCampaign: field("utm_campaign"),
            inviterId: field("inviter_id"),
            promoCode: field("promo_code"),
            idempotencyKey: UUID().uuidString,
            createdAt: now,
            expiresAt: now + transactionTTL
        )

        return record.isValid ? record : nil
    }

    private func processRecord(
        _ record: PendingAttributionRecord
    ) {
        guard record.isValid,
              let processor =
                  HostAppDependencies.parameterProcessor
        else {
            state = .retryableFailure
            return
        }

        guard !processingInFlight else {
            return
        }

        processingInFlight = true

        // Bộ xử lý máy chủ phải xác nhận các kết quả
        // phân bổ và phần thưởng bắt buộc một cách độc lập.
        processor.process(record: record) {
            [weak self] outcome in

            DispatchQueue.main.async {
                guard let self = self,
                      self.activeRecord?.idempotencyKey ==
                          record.idempotencyKey
                else {
                    return
                }

                self.processingInFlight = false

                switch outcome {
                case .completed:
                    self.finalizeRecord(
                        record,
                        terminalState: .applied
                    )

                case .rejected:
                    self.finalizeRecord(
                        record,
                        terminalState: .rejected
                    )

                case .retryableFailure:
                    self.state = .retryableFailure
                }
            }
        }
    }

    private func finalizeRecord(
        _ record: PendingAttributionRecord,
        terminalState: ParamFetchState
    ) {
        guard activeRecord?.idempotencyKey ==
                  record.idempotencyKey,
              let store =
                  HostAppDependencies.transactionStore
        else {
            state = .retryableFailure
            return
        }

        // Bộ lưu trữ máy chủ phải điều phối hoàn tất bền vững
        // và dọn dẹp cho các nhu cầu tin cậy của ứng dụng.
        guard store.clear() else {
            state = .retryableFailure
            return
        }

        activeRecord = nil
        state = terminalState

        print(
            "OpoInstall: Xử lý tham số cài đặt đã được giải quyết"
        )
    }
}

Ví dụ iOS không cung cấp bộ lưu trữ giao dịch chờ xử lý dựa trên UserDefaults mặc định hoặc máy khách từ xa tự động báo cáo thành công.

Ứng dụng chủ phải cung cấp một bản triển khai lưu trữ và bộ xử lý tham số phù hợp với các yêu cầu về bảo mật, phân tích và quản lý tài khoản của nó.

Khi ứng dụng xử lý các giá trị mang phần thưởng, bộ xử lý không được trả về .completed trước khi quá trình ủy quyền phía máy chủ kết thúc.

Khi payload chỉ bao gồm dữ liệu tiếp thị, việc hoàn tất phải phản ánh sự chấp nhận phân tích hoặc yêu cầu xếp hàng đáng tin cậy của ứng dụng.

Đối với các bản ghi hỗn hợp, bộ xử lý phải bảo toàn công việc chưa giải quyết cho từng kênh và đảm bảo rằng các callback cũ không thể hoàn tất một giao dịch khác.

Mã đại diện cố ý lược bỏ bộ lập lịch thử lại hoàn chỉnh và nhật ký giao dịch đa kênh bền vững. Những mối quan tâm đó thuộc về việc triển khai ứng dụng chủ và phải được kiểm tra so với vòng đời và phụ trợ thực tế của nó.

Ranh giới tích hợp sản xuất và Danh sách kiểm tra xác thực

Trước khi triển khai bất kỳ ví dụ di động nào, các nhóm kỹ thuật nên xác minh các điều kiện sau.

Đây là các tiêu chí chấp nhận tích hợp, không phải là tuyên bố rằng mã tham chiếu hoặc một bản phát hành SDK cụ thể đã vượt qua thử nghiệm sản xuất.

Ma trận so sánh chiến lược chuyển tham số

Phân tích phương pháp luận về các chiến lược khôi phục tham số

Các hệ thống thu hút người dùng di động sử dụng các phương pháp khác nhau để bảo toàn ngữ cảnh giới thiệu và phân bổ giữa các lượt truy cập web và ứng dụng native.

Cách tiếp cận phù hợp phụ thuộc vào nền tảng đích, loại tham số bắt buộc, ma sát người dùng có thể chấp nhận, độ nhạy dữ liệu và các cơ chế nền tảng khả dụng.

Đánh giá độ chính xác, tuân thủ quyền riêng tư, ma sát người dùng và ranh giới bảo mật

Nhập mã khuyến mãi thủ công dễ hiểu về mặt kỹ thuật nhưng có thể gây ma sát cho người dùng.

Google Play Install Referrer cung cấp một kênh giới thiệu Android native, được cửa hàng hỗ trợ.

SDK khôi phục tham số bên thứ ba có thể cung cấp lớp tích hợp cấp ứng dụng cho ngữ cảnh trì hoãn đủ điều kiện. Tuy nhiên, phạm vi bao phủ phân phối thực tế, cơ chế kỹ thuật và các đặc tính quyền riêng tư của nó phải được đánh giá bằng bản phát hành đã triển khai.

Bất kể phương thức khôi phục là gì, ứng dụng phải phân biệt giữa việc nhận một tham số và ủy quyền cho một hành động kinh doanh.

Khắc phục sự cố khôi phục tham số, quản lý trạng thái và lỗi tích hợp SDK

Quản lý chuyển đổi trạng thái phía khách hàng: Xử lý không khớp, thử lại và kết quả cuối cùng

Một quy trình khôi phục tham số có thể được mô tả bằng bảy trạng thái logic:

Các trạng thái này mô tả kết quả cấp ứng dụng. Chúng không thay thế cho sự phối hợp bền vững của ứng dụng chủ đối với phân tích, phần thưởng, lưu trữ và thử lại.

Cụ thể, một bản ghi chỉ tiếp thị có thể hoàn tất mà không cần ủy quyền phần thưởng, trong khi một bản ghi mang phần thưởng phải nhận được phản hồi phù hợp từ máy chủ.

Kết quả NO_MATCH không nên được giải thích là bằng chứng xác định rằng việc cài đặt là hữu cơ.

Giải quyết tình trạng hết thời gian yêu cầu tham số và độ trễ mạng một cách khéo léo

Quá trình khôi phục tham số có thể bị ảnh hưởng bởi kết nối, thời gian callback, thứ tự khởi động ứng dụng hoặc các dịch vụ phụ trợ không khả dụng.

Các ứng dụng nên:

• Giữ công việc mạng không đồng bộ.
• Tránh chặn giao diện người dùng chính trong khi truy xuất tham số cài đặt.
• Phân biệt trình quản lý SDK không khả dụng với kết quả tham số trống.
• Coi các lỗi lưu trữ cục bộ là lỗi xử lý, chứ không phải xác nhận rằng không có bản ghi nào tồn tại.
• Thử lại theo chính sách ứng dụng có giới hạn thay vì liên tục đưa ra yêu cầu trong mọi chuyển đổi nền trước.
• Bảo toàn bản ghi chờ xử lý hiện có khi một hoạt động phải được thử lại.

Bất kỳ bản triển khai nào tự động thử lại đều nên ngăn chặn các yêu cầu chồng chéo và từ chối các callback thuộc về các giao dịch đã bị thay thế.

Quản lý cài đặt ghi đè ứng dụng và bộ đệm tham số cũ

Việc khôi phục tham số thường nhắm mục tiêu vào lần khởi chạy đầu tiên sau khi cài đặt hợp lệ, nhưng các bản nâng cấp ứng dụng và khởi chạy lặp lại có thể làm lộ trạng thái cục bộ đã lưu trữ trước đó.

Các nhóm kỹ thuật nên xác định thời điểm nỗ lực khôi phục là đủ điều kiện, cách nhận dạng các bản ghi đã sử dụng và cách dữ liệu chờ xử lý hết hạn.

Đối với các tham số mang phần thưởng, tính lũy đẳng phía máy chủ là rất cần thiết. Một cờ phía khách hàng đơn thuần không phải là sự bảo vệ đầy đủ trước các phần thưởng trùng lặp.

Khi ứng dụng duy trì giao dịch chờ xử lý cục bộ, nó chỉ nên xóa bản ghi sau khi các kết quả xử lý bắt buộc đã được giải quyết một cách bền vững.

Ngăn chặn các vấn đề tái khởi tạo đa quy trình của Android

Các ứng dụng Android với nhiều quy trình có thể thực thi Application.onCreate() nhiều hơn một lần.

Nếu native SDK dự định chỉ khởi tạo trong quy trình ứng dụng chính, các nhà phát triển nên xác minh quy trình hiện tại trước khi khởi tạo nó.

Mẫu Android minh họa một chiến lược so sánh tên quy trình. Các ứng dụng sản xuất nên kiểm tra cách tiếp cận so với các phiên bản Android được hỗ trợ và kiến trúc quy trình của chúng.

Gỡ lỗi không khớp chữ ký callback khách hàng và các quy tắc làm mờ (obfuscation) trình làm co mã

Tên gói, giao diện callback và khai báo lớp của SDK bên thứ ba có thể khác nhau giữa các bản phát hành.

Khi tích hợp thất bại, nhà phát triển nên xác thực SDK đã triển khai thay vì giả định rằng các giao diện mẫu vẫn không thay đổi.

Đối với các bản dựng phát hành Android:

• Ưu tiên các quy tắc R8 / ProGuard của người tiêu dùng được cung cấp kèm theo thành phần SDK chính xác.
• Tránh các quy tắc -keep hoặc -dontwarn trên toàn bộ gói mà không có bằng chứng.
• Kiểm tra các yêu cầu phản xạ (reflection) thực tế trước khi thêm các quy tắc bổ sung hẹp.
• Kiểm tra callback tham số cài đặt trong cấu hình phát hành đã thu nhỏ.

Mã trong hướng dẫn này là một bản tích hợp đại diện và không nên được mô tả là đã xác minh phát hành nếu không có bằng chứng xây dựng và thời gian chạy tương ứng.

Tóm tắt và Khung quyết định

Việc ghép nối lượt nhấp web với cài đặt cửa hàng ứng dụng di động yêu cầu một cách tiếp cận khôi phục tham số tôn trọng ranh giới kỹ thuật giữa trình duyệt, cửa hàng ứng dụng và ứng dụng native.

Đối với Android, API Google Play Install Referrer cung cấp một cơ chế giới thiệu chính thức cho các luồng cài đặt được hỗ trợ. Đối với iOS, các tham số web tùy ý không tự động được phân phối qua App Store, vì vậy việc khôi phục trì hoãn yêu cầu một cách tiếp cận được xác minh độc lập và chú trọng quyền riêng tư.

Việc tích hợp OpoInstall thực tế có thể thu thập các tham số trang đích trong danh sách cho phép và yêu cầu ngữ cảnh đủ điều kiện thông qua native SDK. Sau đó, ứng dụng phải chuẩn hóa và xác thực dữ liệu được khôi phục trước khi sử dụng nó cho phân bổ tiếp thị, điều hướng hoặc các quy trình khuyến mãi.

Sự khác biệt kỹ thuật chính nằm ở khôi phục tham số và xử lý phía ứng dụng. Việc khôi phục một tham số không đảm bảo việc phân phối phân tích, tính đủ điều kiện nhận phần thưởng hoặc ủy quyền thành công.

Mã tham chiếu minh họa ranh giới tích hợp SDK và các hợp đồng do ứng dụng định nghĩa. Các nhóm sản xuất phải cung cấp bộ lưu trữ được bảo vệ, xử lý phân tích đáng tin cậy, xác minh quyền lợi phía máy chủ và phối hợp vòng đời của riêng họ.

Để khám phá các yêu cầu tích hợp nhà cung cấp, hãy tham khảo Tài liệu SDK OpoInstall hoặc trang đăng ký nhà phát triển OpoInstall.

Tài liệu liên quan

Khái niệm: Cài đặt tham số ứng dụng, Google Play Install Referrer, Khôi phục tham số trì hoãn, Phân tích phân bổ từ xa, Ranh giới ủy quyền máy chủ.

Công nghệ: Web JS SDK, Native Mobile SDK, Tham số truy vấn URL, Android Keystore, iOS Keychain Services.

Tiêu chuẩn: Cú pháp URI IETF RFC 3986, Tiêu chuẩn xác minh bảo mật ứng dụng di động OWASP, API và sự kiện Clipboard W3C.

API: API tham số cài đặt OpoInstall Native, API Google Play Install Referrer, API Apple UIPasteboard, API Android Clipboard.

Tài liệu chính thức & Tham chiếu:

• Apple Developer — Quyền riêng tư của người dùng và việc sử dụng dữ liệu

• Android Developers — API Google Play Install Referrer

• W3C — Đặc tả sự kiện và API Clipboard

• OpoInstall — Tài liệu tích hợp SDK