Attributes, tags, and subscriptions

Audience data is queued durably and synchronized by the SDK. Choose the scope deliberately.

Installation-scoped data

Use installation attributes for properties of one app installation or device experience: theme, local onboarding state, device capability, or an installation-specific choice.


Engage.installation.editAttributes {
    set("app.theme", "dark")
    set("notifications.transactional", true)
}


await Engage.installation.editAttributes((attributes) {
  attributes.set('app.theme', 'dark');
  attributes.set('notifications.transactional', true);
});


try await Engage.installation.editAttributes {
    $0.set("app_theme", "dark")
    $0.set("onboarding_complete", true)
}

Profile-scoped data

Use profile attributes and tags for person-level facts that should follow the user across installations.


Engage.profile.editAttributes {
    set("first_name", "Ada")
    set("loyalty.tier", "gold")
    remove("legacy_status")
}
 
Engage.profile.editTags {
    add("beta_tester")
    remove("onboarding_pending")
}


await Engage.profile.editAttributes((attributes) {
  attributes.set('first_name', 'Ada');
  attributes.set('loyalty.tier', 'gold');
  attributes.remove('legacy_status');
});
 
await Engage.profile.editTags((tags) {
  tags.add('beta_tester');
  tags.remove('onboarding_pending');
});


try await Engage.profile.editAttributes {
    $0.set("first_name", "Ada")
    $0.set("loyalty.tier", "gold")
    $0.remove("legacy_status")
}
 
try await Engage.profile.editTags {
    $0.add("beta_tester")
    $0.remove("onboarding_pending")
}

Profile data is meaningful after identity binding. Do not store passwords, payment details, authentication tokens, or unnecessary sensitive personal data in attributes.

Subscription lists

Subscription lists are defined in the Engage console. They may support installation or profile scope and one or more channels: push, email, SMS, and WhatsApp.


Engage.installation.editSubscriptions {
    subscribe("product_updates")
}
 
Engage.profile.editSubscriptions {
    subscribe("weekly_digest", setOf(Channel.EMAIL, Channel.PUSH))
    unsubscribe("promotions", setOf(Channel.SMS))
}


await Engage.installation.editSubscriptions((subscriptions) {
  subscriptions.subscribe('product_updates');
});
 
await Engage.profile.editSubscriptions((subscriptions) {
  subscriptions.subscribe('weekly_digest', {Channel.email, Channel.push});
  subscriptions.unsubscribe('promotions', {Channel.sms});
});


try await Engage.installation.editSubscriptions {
    $0.subscribe("product_updates")
}
 
try await Engage.profile.editSubscriptions {
    $0.subscribe("weekly_digest", channels: [.email, .push])
    $0.unsubscribe("promotions", channels: [.sms])
}

The SDK distinguishes a subscription-list choice from the platform notification permission and from the global Engage push opt-in. Delivery requires every applicable layer to be eligible.

Data naming

Use stable, namespaced keys such as commerce.lifetime_value or app.onboarding_complete. Define type and ownership before emitting a key. Changing a key creates a new audience field; it does not migrate the old value automatically.

Delivery and retries

Editor operations are persisted locally and batched. Do not wrap them in an infinite application retry loop. Await a call when your UI needs immediate validation feedback; otherwise let the SDK synchronize when the network returns.