Singular

Singular là nền tảng Mobile Measurement Partner (MMP) thu thập và trình bày dữ liệu từ các chiến dịch marketing.

Adapty gửi các sự kiện gói đăng ký mà bạn chọn đến Singular. Trong dashboard của Singular, bạn có thể xem mỗi chiến dịch tạo ra bao nhiêu doanh thu và đánh giá hiệu quả quảng cáo của mình.

Thiết lập tích hợp

Kết nối Adapty với Singular

Để thiết lập tích hợp với Singular, hãy vào Integrations > Singular trong Adapty Dashboard, bật toggle và điền thông tin vào các trường.

Các thông tin xác thực sau đây có sẵn:

Singular SDK Key: Bắt buộc. SDK key cho môi trường production của ứng dụng Singular.
Singular SDK Key (Sandbox): Tùy chọn. SDK key cho ứng dụng Singular trong môi trường sandbox. Nếu không được thiết lập, các sự kiện sandbox sẽ không được gửi đến Singular.

Cả hai khóa đều có thể tìm thấy trong Singular dashboard tại Developer tools -> SDK Keys -> SDK Key (không phải SDK Secret):

Cấu hình sự kiện và thẻ tag

Bên dưới phần thông tin xác thực, có ba nhóm sự kiện bạn có thể gửi đến Singular từ Adapty. Để xem danh sách đầy đủ các sự kiện của Adapty, hãy xem Sự kiện.

Chúng tôi khuyên bạn sử dụng tên sự kiện mặc định do Adapty cung cấp. Tuy nhiên, bạn có thể thay đổi tên sự kiện theo nhu cầu của mình.

Adapty gửi các sự kiện gói đăng ký đến máy chủ Singular theo phương thức server-to-server, vì vậy bạn có thể xem tất cả các sự kiện gói đăng ký trong Singular dashboard và liên kết chúng với các chiến dịch quảng cáo của mình.

Warning

Các hồ sơ người dùng được tạo trước khi bạn thiết lập tích hợp sẽ không thể gửi sự kiện đến Singular.

Kết nối ứng dụng với Singular

Singular bật Singular Device ID (SDID) theo mặc định cho các tài khoản được tạo từ ngày 15 tháng 7 năm 2026 trở đi. Các tài khoản này chỉ chấp nhận sự kiện qua v2 Event API, và Adapty chỉ gửi sự kiện đến v2 khi hồ sơ người dùng có SDID. Để gửi sự kiện đến tài khoản như vậy, hãy truyền SDID vào Adapty từ ứng dụng của bạn.

Nếu tài khoản Singular của bạn được tạo trước ngày 15 tháng 7 năm 2026 và SDID chưa được bật, hãy bỏ qua bước này. Adapty sẽ gửi sự kiện của bạn đến v1 Event API và không cần thay đổi code trong ứng dụng.

Kích hoạt Adapty, sau đó khởi động Singular SDK với callback SDID: sdidReceivedHandler trên iOS, SDIDAccessorHandler trên Android, sdidReceivedCallback trên React Native và Flutter, và SingularSdidAccessorHandler trên Unity.
Chờ Singular gọi callback. SDID được gửi đến ứng dụng của bạn theo cách bất đồng bộ, sau khi Singular SDK khởi động. Singular gọi callback mỗi lần khởi chạy, kể cả khi SDID đã được lưu trên thiết bị.
Trong callback, truyền SDID vào Adapty bằng setIntegrationIdentifier() với key singular_sdid. Không có Adapty SDK nào có hằng số định sẵn cho key này, vì vậy hãy viết key dưới dạng chuỗi ký tự.
Chỉ gọi Adapty.identify() sau khi setIntegrationIdentifier() hoàn tất. Adapty tạo một hồ sơ người dùng ẩn danh lúc kích hoạt, sau đó chuyển sang hồ sơ người dùng đã xác định khi identify() hoàn thành. SDID được đặt trong quá trình chuyển đổi đó có thể bị mất.


let config = SingularConfig(apiKey: "<SINGULAR_SDK_KEY>", andSecret: "<SINGULAR_SDK_SECRET>")

config.sdidReceivedHandler = { sdid in
    Task {
        do {
            try await Adapty.setIntegrationIdentifier(
                AdaptyIntegrationIdentifier(key: "singular_sdid", value: sdid)
            )
            // Call Adapty.identify() here, if your app identifies users
        } catch {
            // handle the error
        }
    }
}

Singular.start(config)

val config = SingularConfig("<SINGULAR_SDK_KEY>", "<SINGULAR_SDK_SECRET>")
    .withCustomSdid(null, object : SDIDAccessorHandler {
        override fun didSetSdid(result: String) {}

        override fun sdidReceived(result: String) {
            Adapty.setIntegrationIdentifier(
                AdaptyIntegrationIdentifier(AdaptyIntegrationIdentifier.Key("singular_sdid"), result)
            ) { error ->
                if (error != null) {
                    // handle the error
                    return@setIntegrationIdentifier
                }
                // Call Adapty.identify() here, if your app identifies users
            }
        }
    })

Singular.init(context, config)

SingularConfig config = new SingularConfig("<SINGULAR_SDK_KEY>", "<SINGULAR_SDK_SECRET>")
    .withCustomSdid(null, new SDIDAccessorHandler() {
        @Override
        public void didSetSdid(String result) {}

        @Override
        public void sdidReceived(String result) {
            Adapty.setIntegrationIdentifier(
                new AdaptyIntegrationIdentifier(new AdaptyIntegrationIdentifier.Key("singular_sdid"), result),
                error -> {
                    if (error != null) {
                        // handle the error
                        return;
                    }
                    // Call Adapty.identify() here, if your app identifies users
                }
            );
        }
    });

Singular.init(context, config);


const config = new SingularConfig('<SINGULAR_SDK_KEY>', '<SINGULAR_SDK_SECRET>')
  // null keeps the SDID that Singular generates. Singular's typings require a string.
  .withCustomSdid(null as unknown as string, () => {}, async (sdid) => {
    try {
      await adapty.setIntegrationIdentifier('singular_sdid', sdid);
      // Call adapty.identify() here, if your app identifies users
    } catch (error) {
      // handle `AdaptyError`
    }
  });

Singular.init(config);


final config = SingularConfig('<SINGULAR_SDK_KEY>', '<SINGULAR_SDK_SECRET>');

config.sdidReceivedCallback = (String sdid) async {
  try {
    await Adapty().setIntegrationIdentifier(
      key: 'singular_sdid',
      value: sdid,
    );
    // Call Adapty().identify() here, if your app identifies users
  } on AdaptyError catch (adaptyError) {
    // handle the error
  } catch (e) {
    // handle the error
  }
};

Singular.start(config);

using AdaptySDK;
using Singular;

public class SingularSdidHandler : SingularSdidAccessorHandler
{
    public void DidSetSdid(string result) {}

    public void SdidReceived(string result)
    {
        Adapty.SetIntegrationIdentifier(
            "singular_sdid",
            result,
            (error) => {
                if (error != null) {
                    // handle the error
                    return;
                }
                // Call Adapty.Identify() here, if your app identifies users
            });
    }
}

// Register the handler before the Singular SDK initializes
SingularSDK.SetSingularSdidAccessorHandler(new SingularSdidHandler());

// Call this from the SDID callback of the native Singular SDK
// on each platform: sdidReceivedHandler on iOS, SDIDAccessorHandler on Android
suspend fun onSingularSdidReceived(sdid: String) {
    Adapty.setIntegrationIdentifier("singular_sdid", sdid)
        .onSuccess {
            // Call Adapty.identify() here, if your app identifies users
        }
        .onError { error ->
            // handle the error
        }
}


// Call this from the SDID callback of the Singular SDK
async function onSingularSdidReceived(sdid: string) {
  try {
    await adapty.setIntegrationIdentifier({ key: 'singular_sdid', value: sdid });
    // Call adapty.identify() here, if your app identifies users
  } catch (error) {
    // handle the error
  }
}

Cấu trúc sự kiện

Adapty chọn phiên bản Singular Event API cho từng sự kiện dựa trên việc hồ sơ người dùng có SDID hay không:

Có SDID: Adapty gửi yêu cầu POST đến https://s2s.singular.net/api/v2/evt với body dạng form-urlencoded. Tham số sdid thay thế các định danh thiết bị idfa, idfv, aifa, andi, và asid. Giá trị boolean được gửi dưới dạng true hoặc false.
Không có SDID: Adapty gửi yêu cầu GET đến https://s2s.singular.net/api/v1/evt với các query parameter.

Cả hai phiên bản đều mang các tham số giống nhau. Một sự kiện v1 có cấu trúc như sau:

{
  "n": "subscription_renewed",
  "a": "singular_sdk_key_123",
  "p": "iOS",
  "i": "com.example.app",
  "ip": "192.168.100.1",
  "idfa": "00000000-0000-0000-0000-000000000000",
  "idfv": "00000000-0000-0000-0000-000000000000",
  "ve": "17.0.1",
  "att_authorization_status": 3,
  "custom_user_id": "user_12345",
  "utime": 1709294400,
  "partner": "adapty",
  "use_ip": false,
  "is_revenue_event": true,
  "amt": 9.99,
  "cur": "USD",
  "purchase_product_id": "yearly.premium.6999",
  "purchase_transaction_id": "GPA.3383...",
  "e": "{\"is_revenue_event\":true,\"amt\":9.99,\"cur\":\"USD\",\"purchase_product_id\":\"yearly.premium.6999\",\"purchase_transaction_id\":\"GPA.3383...\"}"
}

Trong đó:

Tham số	Kiểu	Mô tả
`n`	String	Tên sự kiện (được ánh xạ từ sự kiện Adapty).
`a`	String	Singular SDK Key của bạn.
`p`	String	Nền tảng (“iOS” hoặc “Android”).
`i`	String	Store App ID (Bundle ID).
`ip`	String	Địa chỉ IP của người dùng.
`sdid`	String	Chỉ v2. Singular Device ID, lấy từ integration identifier `singular_sdid`.
`idfa`	String	iOS, chỉ v1. ID for Advertisers (chữ hoa).
`idfv`	String	iOS, chỉ v1. ID for Vendors (chữ hoa).
`aifa`	String	Android, chỉ v1. Google Advertising ID (chữ thường).
`andi`	String	Android, chỉ v1. Android ID (chữ thường).
`asid`	String	Android, chỉ v1. App Set ID (chữ thường).
`ve`	String	Phiên bản OS.
`att_authorization_status`	Integer	Chỉ iOS. Trạng thái ATT (ví dụ: `3` là đã ủy quyền).
`custom_user_id`	String	Customer User ID của người dùng.
`utime`	Long	UNIX timestamp của sự kiện tính bằng giây.
`partner`	String	Luôn là `adapty`. Xác định sự kiện được gửi bởi Adapty.
`use_ip`	Boolean	`true` khi Adapty không có địa chỉ IP của người dùng.
`is_revenue_event`	Boolean	`true` nếu sự kiện có chứa doanh thu. Chỉ gửi kèm các sự kiện có doanh thu.
`amt`	Float	Số tiền doanh thu.
`cur`	String	Mã tiền tệ (ví dụ: “USD”).
`purchase_product_id`	String	Product ID từ cửa hàng.
`purchase_transaction_id`	String	Transaction ID gốc.
`e`	String	Chuỗi JSON chứa chi tiết sự kiện (xem bên dưới).

Tham số e (dữ liệu sự kiện tùy chỉnh) là một chuỗi được mã hóa JSON chứa:

Parameter	Type	Description
`is_revenue_event`	Boolean	`true` nếu sự kiện có chứa doanh thu.
`amt`	Float	Số tiền doanh thu.
`cur`	String	Mã tiền tệ.
`purchase_product_id`	String	ID sản phẩm từ cửa hàng.
`purchase_transaction_id`	String	ID giao dịch gốc.

Khắc phục sự cố

Sự kiện thất bại với lỗi `invalid api version: v1`

Tài khoản Singular của bạn được tạo vào hoặc sau ngày 15 tháng 7 năm 2026, và chỉ chấp nhận sự kiện thông qua Event API v2. Adapty đã gửi sự kiện đến v1 vì hồ sơ người dùng không có SDID. Để khắc phục, hãy truyền SDID vào Adapty từ ứng dụng của bạn, như được mô tả trong Kết nối ứng dụng của bạn với Singular. Các sự kiện từ người dùng đang dùng phiên bản ứng dụng chưa có lệnh gọi setIntegrationIdentifier() sẽ tiếp tục thất bại cho đến khi những người dùng đó cập nhật ứng dụng.

`access_level_updated` hiển thị là thất bại trong Event Feed

access_level_updated là một sự kiện chỉ dành cho webhook. Adapty không bao giờ gửi sự kiện này đến tích hợp này. Tuy nhiên, Adapty ghi lại kết quả cho mọi tích hợp đã bật, và một sự kiện không được hỗ trợ sẽ được hiển thị là thất bại.

Singular

Thiết lập tích hợp

Kết nối Adapty với Singular

Cấu hình sự kiện và thẻ tag

Kết nối ứng dụng với Singular

Cấu trúc sự kiện

Khắc phục sự cố

Sự kiện thất bại với lỗi invalid api version: v1

access_level_updated hiển thị là thất bại trong Event Feed

Sự kiện thất bại với lỗi `invalid api version: v1`

`access_level_updated` hiển thị là thất bại trong Event Feed