|Singular Unity SDK|
||Singular Unity SDK version 4.0.8 (see Change Log)|
|Sample App||Review our sample app for an example of a complete SDK integration based on best practices.|
Adding Ad Revenue Attribution Support
Note: Starting in version 3.0.0, Singular added the option to set up ad revenue attribution through the Singular SDK.
Ad revenue attribution can still be set up the old way, using API calls, without updating the Singular SDK in your apps. However, if you want to measure ad revenue for SKAdNetwork campaigns, you have to set up ad revenue attribution through the SDK.
To add ad revenue attribution support in the Singular SDK:
- If you haven't done so yet, contact your Singular Customer Success Manager to enable ad revenue attribution for your account.
- Update to the latest version of the Singular SDK.
- Add the appropriate code snippet to your Singular SDK integration, depending on the mediation platform you use for ad revenue data.
// Note: This is a beta feature. Contact Admob to have it enabled.
public void HandleRewardedAdLoaded(object sender, EventArgs args)
this.rewardedAd = args.rewardedAd;
private void HandleAdPaidEvent(object sender, AdValueEventArgs args)
this.impressionData = args.AdValue;
SingularAdData data = new SingularAdData("Admob", impressionData.CurrencyCode, impressionData.Value/1000000f);
// The object received from AppLovin MAX's event: OnInterstitialAdRevenuePaidEvent MaxSdkBase.AdInfo impressionData; string adUnitId; double revenue = MaxSdk.GetAdInfo(adUnitId).Revenue; SingularAdData data = new SingularAdData("AppLovin","USD", revenue); data.WithAdUnitId(impressionData.AdUnitIdentifier). WithNetworkName(impressionData.NetworkName). WithAdPlacementName(impressionData.Placement); Singular.AdRevenue(data);
// The object received from IronSource's event: OnImpressionSuccess IronSourceImpressionData impressionData; SingularAdData data = new SingularAdData("IronSource","USD", impressionData.revenue); data.WithAdUnitId(impressionData.getInstanceId). WithAdUnitName(impressionData.getInstanceName). WithImpressionId(impressionData.getAuctionId). WithNetworkName(impressionData.adNetwork). WithAdPlacementName(impressionData.placement). WithAdType(impressionData.getAdUnit); Singular.AdRevenue(data);
// Ensure that the ARM SDK Postbacks Flag (click here) in IronSource is turned on
// The object received from MoPub's event: OnImpression ImpressionData impressionData; SingularAdData data = new SingularAdData("Mopub", impressionData.Currency, impressionData.PublisherRevenue); data.WithAdGroupId(impressionData.AdGroupId). WithAdGroupName(impressionData.AdGroupName). WithAdGroupType(impressionData.AdGroupType). WithAdGroupPriority(impressionData.AdGroupPriority). WithAdUnitId(impressionData.AdUnitId). WithAdUnitName(impressionData.AdUnitName). WithImpressionId(impressionData.ImpressionId). WithNetworkName(impressionData.NetworkName). WithAdPlacementName("AD_PLACEMENT_NAME"). WithAdType("AD_TYPE"); Singular.AdRevenue(data);
// Initialize the SingularAdData object with the relevant data SingularAdData data = new SingularAdData("YOUR_AD_PLATFORM", "CURRENCY_CODE", 9.90). // The more ad data you add, the greater the granularity data.WithAdGroupId("AD_GROUP_ID") .WithNetworkName("AD_NETWORK_NAME"); // Report the data to Singular SingularSDK.AdRevenue(data);
Note: Uninstall tracking is only available to Enterprise customers.
Android Uninstall Tracking
To enable uninstall tracking for your Android app, first configure the app in the Singular platform as detailed in Setting Up Uninstall Tracking. Then follow the instructions below.
Note: Google deprecated the GCM APIs on April 2018. Use FCM for uninstall tracking.
Enabling Uninstall Tracking Using Firebase Cloud Messaging (FCM)
1. Integrate with FCM:
To track uninstalls, you can use the services of the Firebase Cloud Messaging (FCM) platform. If you are not already using FCM follow Google's instructions on how to Set up a Firebase Cloud Messaging client app on Android.
FCM Requirements (source)
FCM clients require devices running Android 4.1 or higher that also have the Google Play Store app installed, or an emulator running Android 4.1 with Google APIs. Note that you are not limited to deploying your Android apps through Google Play Store.
Users/devices who are not running on supported versions of Android will not be available for Singular uninstall tracking.
2. Update the AndroidManifest.xml File:
Update your AndroidManifest.xml file to add the necessary intent filter for your app (replace MyFirebaseMessagingService with your class that implements the Firebase Service):
<action android:name="com.google.firebase.MESSAGING_EVENT" />
</intent-filter> </service> <service android:name=".java.MyFirebaseMessagingService" android:exported="false"> intent-filter> action android:name="com.google.firebase.MESSAGING_EVENT" /> </intent-filter> </service>
3. Register and Send the FCM Device Token:
Finally, set the FCM device token after your SingularConfig is initialized in OnCreate(), as follows:
iOS Uninstall Tracking
Uninstall tracking on iOS is based on Apple push-notification technology. If your app doesn't currently support push notifications, see Apple's guide. If your app already supports push notifications, all you need to do is pass the device token returned from APNS using the RegisterDeviceTokenForUninstall method, after the SDK is initialized.
|Description||Pass the device token returned from APNS. Note that the APNS token is usually binary data in the native form, but you need to pass it as a string.|
Adding Global Properties
The Singular SDK lets you define custom additional properties that you want to send to the Singular servers with every session and event sent from the app. These properties can represent any information you want about the user, the app mode or status, or anything else. Once you set these properties, they are available as dimensions in your reports and you can use them to break down your data.
For example, if you have a gaming app, you can define a property called "Level" and set it initially to "0". Any session and event sent from the app will be sent with "Level": "0". Once the user levels up you reset the property to "1" and so on. You can then get your reports, including sessions, event counts, and revenue data, broken down by user level.
- You can define up to 5 global properties.
- They persist between app runs (with the latest value you gave them) until you unset them or the user uninstalls the app.
- Each property name and value can be up to 200 characters long. If you pass a longer property name or value, it will be truncated to 200 characters.
- Global properties are accessible and available in user-level exports and postbacks. In the future, aggregate reporting support will be added. Let your Singular customer success manager know if you have any questions or are interested in updates to global properties support!
Setting Global Properties before Initialization
You can use the SetGlobalProperty method to set global properties through SingularSDK before initializing the SDK. Make sure to turn off the `Initialize On awake` flag if you want your global properties to be included in the session.
Note that since global properties and their values persist between app runs, the property that you are setting may already be set to a different value. Use the overrideExisting parameter to tell the SDK whether to override an existing property with the new value or not.
Setting Global Properties After Initialization
Use the following methods to set, unset, and retrieve global properties at any time in the app's run.
Set a global property to a given value.
|Signature||public static bool SetGlobalProperty(string key, string value, bool overrideExisting)|
|Description||Retrieve all the global properties and their current values as a Map.|
|Signature||public static Dictionary<string, string> GetGlobalProperties()|
|Description||Remove a global property.|
|Signature||public static void UnsetGlobalProperty(string key)|
|Description||Remove all global properties.|
|Signature||public static void ClearGlobalProperties()|
Complying with Data Privacy Laws
Singular provides privacy-safeguarding functionality to help you cooperate with any partners who may be complying with consumer privacy laws such as GDPR and CCPA (California Consumer Privacy Act). These partners want to be notified if the end-user has consented to share their private information.
If you have implemented a way to ask users for consent to share their information, use the LimitDataSharing method to notify Singular of the user's choice:
- Use SingularSDK.LimitDataSharing(false) to indicate that the user consented (opted in) to share their information.
- Use SingularSDK.LimitDataSharing(true) if the user did not consent.
Singular will pass this information on to partners who require it in order to comply with relevant regulations.
Note: The use of the method is optional, but there may be attribution information that the partner will share with Singular only if specifically notified that the user has opted in.
|Description||Notify Singular of user consent (opt-in) for sharing private data.|
The Singular SDK provides several methods to help you comply with GDPR policies and let Singular know about user consent or non-consent for tracking.
|Description||Notify Singular of user consent (opt-in) for tracking.|
|Description||Stop all tracking activities for this user on this app.
Note: Calling this method effectively disables the SDK, even after the app restarts (the state is persistent)! The only way to re-enable tracking is by calling resumeAllTracking().
|Description||Resume tracking for this user on this app.|
|Description||Check the tracking status for this user on this app. Returns true if tracking has been stopped using StopAllTracking() and not resumed.|