Singular
With our Singular integration you can:
- Accurately track subscriptions generated from Singular campaigns, allowing you to know precisely how much revenue your campaigns generate.
- Send trial conversions and renewals directly from RevenueCat to Singular, allowing for tracking without an app open.
- Continue to follow your cohorts for months to know the long tail revenue generated by your campaigns.
Integration at a Glance
| Includes Revenue | Supports Negative Revenue | Sends Sandbox Events | Includes Customer Attributes | Sends Transfer Events | Optional Event Types |
|---|---|---|---|---|---|
| ✅ | ✅ | Requires sandbox SDK key | Certain Reserved Attributes only | ❌ | non_subscription_purchase_event uncancellation_event subscription_paused_event expiration_event billing_issues_event product_change_event |
1. Send device data to RevenueCat
The Singular integration requires some device-specific data. RevenueCat will only send events into Singular if the below Customer Attribute keys have been set for the device.
| Key | Description | Required |
|---|---|---|
$idfa | iOS advertising identifier UUID | ✅ (iOS only) |
$idfv | iOS vender identifier UUID | ✅ (iOS only) |
$gpsAdId | Google advertising identifier | ✅ (Android only) |
$ip | The IP address of the device | ❌ (optional) |
Due to policy changes from the Play Store, Android ID is no longer collected by RevenueCat's Android SDKs starting on versions 6.9.8+, 7.11.1+, and later major versions.
Therefore, Google's Advertising ID acts as the primary device identifier for Android devices in RevenueCat and when connecting with third-party integrations.
These properties can be set manually, like any other Attributes, or through the helper method collectDeviceIdentifiers().
- Swift
- Kotlin
import AdSupport
// ...
Purchases.configure(withAPIKey: "public_sdk_key")
// ...
Purchases.shared.attribution.collectDeviceIdentifiers()
//..
Purchases.configure(this, "public_sdk_key")
//..
Purchases.sharedInstance.collectDeviceIdentifiers()
You should make sure to call collectDeviceIdentifiers() after the Purchases SDK is configured, and before the first purchase occurs. It's safe to call this multiple times, as only the new/updated values will be sent to RevenueCat.
Since we deliver server-to-server events via API, as opposed to on the SDK where SKAN can be interacted with, this integration does not allow you to modify SKAN conversion values directly from received RevenueCat events.
If you are requesting the App Tracking permission through ATT to access the IDFA, you can call .collectDeviceIdentifiers() again if the customer accepts the permission to update the $idfa attribute in RevenueCat.
The AdSupport framework is required to access the IDFA parameter on iOS. Don't forget to import this into your project.
Make sure to remove all client-side tracking of revenue. Since RevenueCat will be sending events for all revenue actions, tracking purchases with the Singular SDK directly can lead to double counting of revenue in Singular.
(Optional) Send campaign data to RevenueCat
RevenueCat itself is not an attribution network, and can't determine which specific ad drove an install/conversion. However, if you're able to collect this information from another source, such as Singular, it's possible to attach it to a user in RevenueCat using Customer Attributes as well.
The below reserved key names can be used to optionally attach campaign data to a user. This data will then be sent through to other downstream analytics integrations and accessible via APIs and webhooks.
| Key |
|---|
$mediaSource |
$campaign |
$adGroup |
$ad |
$keyword |
$creative |
2. Send RevenueCat events into Singular
After you've set up the Purchases SDK to send device data to RevenueCat, you can "turn on" the integration and configure the event names from the RevenueCat dashboard.
RevenueCat's events do not include receipts from the stores, since we validate purchases before triggering events. Therefore, do NOT enable the 'Reject IAP without Receipt' setting in Singular's Apps page so these events are accepted in Singular after having been validated by RevenueCat.
- Navigate to your project in the RevenueCat dashboard and find the Integrations card in the left menu. Select + New
- Choose Singular from the Integrations menu.
- Add your Singular SDK key, and an optional sandbox SDK key. The sandbox SDK key will be used for any sandbox purchases so you don't have to send them to your production Singular instance.
- Enter the event names that RevenueCat will send or choose the default event names.
- Select whether you want RevenueCat to report proceeds (after app store cut) or revenue (gross sales).
3. Testing the Singular integration
You can test the Singular integration end-to-end before going live. It's recommended that you test the integration is working properly for new users, and any existing users that may update their app to a new version.
Add a sandbox SDK key in the RevenueCat dashboard
Before you test the integration, make sure you have a Singular SDK key set in the "SDK key (sandbox)" field in RevenueCat. This is required if you want the integration to trigger for sandbox purchases.
Make a sandbox purchase with a new user
Simulate a new user installing your app, and go through your app flow to complete a sandbox purchase.
Check that the required device data is collected
Navigate the the Customer View for the test user that just made a purchase. Make sure that all of the required data from step 1 above is listed as attributes for the user.
While we are still sending the Revenue metric for these events, you should not expect to see the event appearing as Revenue in Singular's SDK console. You can verify that the event is processed as a revenue event in the Export logs tool via Singular.
Check that the Singular event delivered successfully
While still on the Customer View, click into the test purchase event in the Customer History and make sure that the Singular integration event exists and was delivered successfully.
You should start seeing events from RevenueCat appear in Singular.