Subscriber Attributes

Adding custom properties to users in RevenueCat

Subscriber attributes are useful for storing additional, structured information on a user. For example, you could store your user's email address and additional system identifiers directly in RevenueCat. Attributes will not be seen by your users unless you choose to explicitly show them yourself.

📘

Subscriber attributes are only synced with RevenueCat servers when Purchases.configure() is called, app backgrounded, and when purchases are made or restored.

Setting Attributes

Subscriber attributes can be set through the SDK by passing a dictionary of strings to the setAttributes() method on the shared Purchases instance.

Purchases.shared.attribution.setAttributes(["age": "24",
                                            "custom_group_id": "abc123"])
[RCPurchases.sharedPurchases.attribution setAttributes:@{
    @"age": @"24",
    @"custom_group_id": @"abc123"
}];
Purchases.sharedInstance.setAttributes(mapOf("age" to "24", "custom_group_id" to "abc123"))
Map<String, String> attributes = new HashMap<String, String>();
attributes.put("age", "24");
attributes.put("custom_group_id", "abc123");

Purchases.getSharedInstance().setAttributes(attributes);
Purchases.setAttributes({ "age" : "24", "custom_group_id" : "abc123" });
Purchases.setAttributes({ "age" : "24", "custom_group_id" : "abc123" });
var purchases = GetComponent<Purchases>();
var attributes = new Dictionary<string, string>
{
    { "age", "24" }, 
    { "custom_group_id", "abc123" }
};
purchases.SetAttributes(attributes);

🚧

Since subscriber attributes are writable using a public key they should not be used for managing secure or sensitive information such as subscription status, coins, etc.

Restrictions

You can specify up to 50 attributes, with key names up to 40 characters long and values up to 500 characters long. Keys cannot start with $ unless it's for one of the reserved attributes below.

Attribute key checklist:
✅ Key does not contain whitespace
✅ Key must start with a letter for non-reserved attributes or "$" for reserved attributes
✅ Key does not include any non-alphanumeric characters except - and _
✅ Key is not more than 40 characters
✅ Value is not more than 500 characters
✅ No more than 50 custom attributes

Reserved attributes

Attribute keys beginning with $ are reserved for RevenueCat. The current list of reserved keys are below:

General

KeyDescription
$displayNameName that should be used to reference the user
$apnsTokensApple push notification tokens for the user.
$fcmTokensGoogle push notification tokens for the user.
$attConsentStatusApple App Tracking Transparency consent status for the user.
$ipAddressIp Address for the user.
$clevertapId Clever Tap ID for the user.
$idfaiOS advertising identifier UUID.
$idfviOS vender identifier UUID.
$gpsAdIdThe advertising ID that is provided by Google Play services.
$androidIdAndroid device identifier.
$amazonAdIdAmazon Advertising ID.
$adjustIdThe unique Adjust identifier for the user.
$amplitudeDeviceIdThe Amplitude Device ID.
$amplitudeUserIdThe Amplitude User ID.
$appsflyerIdAppsflyer Id. The unique Appsflyer identifier for the user.
$brazeAliasNameThe Braze 'alias_name' in User Alias Object.
$brazeAliasLabelThe Braze 'alias_label' in User Alias Object.
$clevertapIdThe CleverTap ID for the user.
$fbAnonIdThe Facebook Anonymous ID for the user.
$attConsentStatusApple App Tracking Transparency consent status for the user.
$mparticleIdThe unique mParticle user identifier (mpid).
$onesignalIdThe OneSignal Player Id for the user.
$airshipChannelIdThe Airship channel ID for the user.
$iterableUserIdThe Iterable ID for the user.
$iterableCampaignIdThe Iterable campaign ID.
$iterableTemplateIdThe Iterable template ID.
$firebaseAppInstanceIdThe Firebase instance identifier.
$mixpanelDistinctIdThe Mixpanel user identifier.
$ipThe IP address of the device.
$emailEmail address for the user.
$phoneNumberPhone number for the user.

🚧

attConsentStatus is populated regardless of requesting any permission

The RevenueCat SDK sends the current ATT status for the $attConsentStatus subscriber attribute regardless of if you are or aren't requesting any ATT permission. So just as a heads-up, you can expect to see this attribute filled.

Note: The RevenueCat SDK reads the current App Tracking Transparency Consent Status for the user, but will not modify it or request for further permission.

You may see the following as a response from this attribute:

  • restricted - Can be returned if the user is using a mobile device management profile that disallows some aspects of tracking regardless of consent. This might be returned even if you never ask for permissions.
  • denied - Can be returned if the user’s phone has set “Ask Apps Not To Track” in OS Settings or denied access for the specific app.
  • accepted - Returned if you ask for permission and the permission gets accepted by the user.
  • unknown - The user hasn’t set “Ask Apps Not to Track” in OS Settings, and you have never asked the user for consent to track activity.

Device Identifiers

KeyDescription
$idfaApple advertising identifier
$idfvApple vendor identifier
$gpsAdIdGoogle advertising identifier
$androidIdAndroid device identifier
$ipIP Address

📘

Device identifiers can't be changed once set

Once a device identifier is set for a subscriber, it can't be changed in order to keep these identifiers associated with the original installation. This allows RevenueCat to send events generated by a particular device to downstream integrations with a consistent identifier unaffected by uninstalls and reinstalls.

Third-party Identifiers

KeyDescription
$adjustIdAdjust user identifier
$amplitudeDeviceIdAmplitude device identifier
$amplitudeUserIdAmplitude user identifier
$appsflyerIdAppsflyer user identifier
$fbAnonIdFacebook SDK anonymous user identifier
$firebaseAppInstanceIdFirebase instance identifier
$iterableUserIdIterable user identifier
$mixpanelDistinctIdMixpanel user identifier
$mparticleIdmParticle user identifier
$onesignalIdOneSignal player identifier
$clevertapIdCleverTap user identifier
$airshipChannelIdAirship channel identifier

Braze User Alias Object

KeyDescription
$brazeAliasNameBraze 'alias_name' in User Alias Object
$brazeAliasLabelBraze 'alias_label' in User Alias Object

Iterable Data

Key
$iterableCampaignId
$iterableTemplateId

Attribution Data

Key
$mediaSource
$campaign
$adGroup
$ad
$keyword
$creative

📘

If you have access to install attribution data, you can set it using the reserved keys above. RevenueCat itself is not an attribution network and can not automatically populate this information.

Once attribution data is set for a subscriber, it can't be changed. This way attribution data can be associated with the original installation without getting overwritten.

Reserved attributes can be written directly by setting the key (don't forget the $ prefix) or with special helper methods:

Purchases.shared.attribution.setEmail("[email protected]")
Purchases.shared.attribution.setPhoneNumber("+16505551234")
Purchases.shared.attribution.setDisplayName("John Appleseed")
[RCPurchases.sharedPurchases.attribution setEmail:@"[email protected]"];
[RCPurchases.sharedPurchases.attribution setPhoneNumber:@"+16505551234"];
[RCPurchases.sharedPurchases.attribution setDisplayName:@"John Appleseed"];
Purchases.sharedInstance.setEmail("[email protected]")
Purchases.sharedInstance.setPhoneNumber("+16505551234")
Purchases.sharedInstance.setDisplayName("John Appleseed")
Purchases.setEmail("[email protected]")
Purchases.setPhoneNumber("+16505551234")
Purchases.setDisplayName("John Appleseed")
Purchases.setEmail("[email protected]")
Purchases.setPhoneNumber("+16505551234")
Purchases.setDisplayName("John Appleseed")
var purchases = GetComponent<Purchases>();
purchases.SetEmail("[email protected]");
purchases.SetPhoneNumber("asdga");
purchases.SetDisplayName("asdgas");

Setting push tokens

Push tokens can be used to engage with your users through Apple apns or Google cloud messaging. These can be saved in RevenueCat through system callbacks after the user accepts the push notification permissions in your app.

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    Purchases.shared.attribution.setPushToken(deviceToken)
}
- (void)application:(UIApplication *)application 
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [RCPurchases.sharedPurchases.attribution setPushToken:deviceToken];
}
Purchases.sharedInstance.setPushToken(deviceToken)
Purchases.setPushToken(deviceToken);
Purchases.setPushToken(deviceToken)
var purchases = GetComponent<Purchases>();
purchases.SetPushToken(deviceToken);

Deleting Attributes

Any attribute can be cleared by passing null or an empty string as the key value. Individual attributes can also be cleared for a specific user in their customer view.

Purchases.shared.attribution.setAttributes(["age": ""])
[RCPurchases.sharedPurchases.attribution setAttributes:@{@"age": @""}];
Purchases.sharedInstance.setAttributes(mapOf("age" to ""))
Purchases.setAttributes({"age" : ""});
Purchases.setAttributes({"age" : ""})
var purchases = GetComponent<Purchases>();
var attributes = new Dictionary<string, string>
{
    { "age", "" }, 
    { "custom_group_id", "" }
};
purchases.SetAttributes(attributes);

Reading Attributes

You can access subscriber attributes through the REST API using a secret key, in webhooks, and through analytics integrations (Amplitude, Mixpanel, Segment). The customer view dashboard will also show a list of attributes for the individual user that you can edit.

📘

Subscriber attributes are write-only from the SDK. Reading attributes should only be done server-side through the webhooks or REST API.

Subscriber attributes are also included with transaction data for Scheduled Data Exports.

Next Steps