Targeting by Custom Attributes

With custom attributes, you can create audiences to target with unique Offerings based on any dimension that's relevant to your business.

Continue reading to learn:

1. How to start setting custom attributes
2. How to create Targeting Rules with custom attributes
3. How to sync custom attributes to serve fresh paywalls

How to start setting custom attributes

Custom attributes can be set through the setAttributes() method in our SDKs, or via API. For full implementation details, visit the Attributes page.

How to create Targeting Rules with custom attributes

First, navigate to your Project and click on Targeting under Monetization tools. Then, click + New to begin creating a new rule.

After setting a display name, click on + Add condition to begin defining your Targeting Rule, and click on Custom attributes to start with that condition.

First, you'll need to select the key of the custom attribute you want to use. If you've set any custom attributes for customers in this Project already, you'll see them in this list. Otherwise, feel free to add a new key that you intend to begin setting for your customers.

After selecting or adding the key you want to use, select whether you want to build an inclusion ("is any of") or exclusion ("is not any of") condition. Last, you'll need to select the set of values to include/exclude in your condition. Just like with keys, you can add values to this list that are not present, just keep in mind that they need to be set for customers in order to impact what Targeting Rule that customer will qualify for.

📘Only 50 sample values will be listed

For keys which have more than 50 unique values that have been set for them, we'll only show 50 in this list. This is just a display limitation -- any other set values can still be entered and used.

How to sync custom attributes to serve fresh paywalls

By default, we'll sync any attributes that you set during an app session when the app is backgrounded. This works great if you're using the attribute for some future need, but if you're looking to use it to serve a unique paywall via Targeting in that same session this is not sufficient.

Therefore, we recommend using the syncAttributesAndOfferingsIfNeeded() method to ensure set attributes can be used for Targeting in the same session.

The syncAttributesAndOfferingsIfNeeded() method

You can use the syncAttributesAndOfferingsIfNeeded() method to explicitly sync attributes mid-session, which will automatically refresh the cached Offering as well, ensuring your customer sees the correct paywall based on any newly set custom attributes without needing to wait it to load.

We recommend using that method after you've set the last attribute that may be used for a paywall you intend to display in that session.

For example, if during your onboarding you set two attributes which may both be used in Targeting Rules, such as onboarding_survey_use_case and onboarding_survey_experience_level to track answers to those onboarding survey questions; we recommend calling syncAttributesAndOfferingsIfNeeded() once after both attributes have been set.

⚠️

Calls to this method have a rate limit of 5 per minute to prevent abuse.

Swift

Purchases.shared.syncAttributesAndOfferingsIfNeeded { offerings, error in
    // Attributes and offerings are synced
}

Kotlin

Purchases.sharedInstance.syncAttributesAndOfferingsIfNeededWith({ error ->
    // An error occurred
}) { offerings ->
    // Attributes and offerings are synced
}

Java

Purchases.getSharedInstance().syncAttributesAndOfferingsIfNeeded(new SyncAttributesAndOfferingsCallback() {
    @Override
    public void onReceived(@NonNull Offerings offerings) {
        // Attributes and offerings are synced
    }

    @Override
    public void onError(@NonNull PurchasesError error) {
        // An error occurred
    }
});