Show an AA-targeted paywall on first launch in Unity SDK

This article applies to the iOS build of your app. Apple Ads attribution exists on iOS only.

Apple Ads (AA) attribution arrives asynchronously after Adapty.Activate(). If you call GetFlow early, attribution often hasn’t landed yet and Adapty resolves the placement against the default audience — bypassing your AA-segmented paywalls. AdaptyProfile.AppliedExternalAttributionProviders lets the app detect when AA attribution has been applied to the profile, so the paywall request can wait until AA segmentation will resolve correctly.

Important

AppliedExternalAttributionProviders only reports Apple Ads. Attribution from other providers is visible on user profiles and available in segment filters, but not yet here.

Before you start

You need:

Adapty Unity SDK 4.1 or later.
Apple Ads configured for the app in Adapty. See Apple Ads.

Note

The examples use the API names from SDK 4.1. On SDK 4.0, the profile property is named AppliedAttributionSources. On SDK 3.x, that property has the same older name, and paywalls are fetched with GetPaywall/GetPaywallForDefaultAudience, which return an AdaptyPaywall. See Migrate Adapty Unity SDK to v4.

How it works

After Adapty.Activate(), the SDK requests Apple Ads attribution from Apple in the background and forwards the result to Adapty’s backend. When AA becomes the active attribution source for the profile, the SDK delivers an updated AdaptyProfile to your OnLoadLatestProfile handler, with AdaptyExternalAttributionProvider.AppleAds in its AppliedExternalAttributionProviders list.

An empty list can mean any of:

Apple Ads attribution hasn’t been processed yet for this profile.
No attribution has arrived at all.
Attribution arrived from another provider, which this list doesn’t report.

Even with an empty list, GetFlow is still safe to call — Adapty resolves the request against whichever audience matches the current profile state, typically the default audience.

Important

The wait only applies to first launch. Once Apple Ads attribution has been recorded, it’s stored on the profile permanently. On every subsequent launch, the cached profile already carries AppleAds in AppliedExternalAttributionProviders, OnLoadLatestProfile fires with that value immediately, and GetFlow returns the Apple-Ads-segmented paywall without any delay.

Implementation

On first launch, watch for AdaptyExternalAttributionProvider.AppleAds in the profile and apply a hard timeout — if the Apple Ads attribution never arrives, those users still need to see a paywall.

Activate the SDK. See Install & configure the Unity SDK.
Subscribe to profile updates by implementing IAdaptyEventListener and registering it with Adapty.SetEventListener. If you haven’t set up the listener yet, see Listen to subscription updates.
Watch for AppleAds in AppliedExternalAttributionProviders. When it appears, request the paywall — Adapty will return the AA-segmented variant:

using System.Linq;

public void OnLoadLatestProfile(AdaptyProfile profile)
{
    if (profile.AppliedExternalAttributionProviders.Contains(AdaptyExternalAttributionProvider.AppleAds))
    {
        // load the paywall via Adapty.GetFlow(placementId, ...)
    }
}

Start a 3–5 second timer in parallel with the subscription. If the timer fires before AppleAds appears, request the default-audience paywall with GetFlowForDefaultAudience instead. It returns the paywall without waiting for segmentation.

Whichever path fires first should load the paywall; the other path should be skipped. Use a single state flag (for example, hasLoadedPaywall) to deduplicate so the paywall isn’t fetched twice. Configure a fallback paywall for the placement so the user is never stuck if the network request fails.

SetEventListener accepts one listener. If your app already uses an IAdaptyEventListener for other purposes (for example, listening to subscription updates), add the check to its existing OnLoadLatestProfile instead of registering a second listener.