Global Attributes

Global Attributes are key–value pairs you set once and NVECTA automatically attaches to the events that follow — so you don't have to repeat them in every trackEvents() call. They're ideal for context that applies broadly across a session, such as a campaign_id, an experiment variant, or a membership_plan you want carried onto many events at once.

Common values passed as Global Attributes include:

• campaign_id
• experiment
• membership_plan
• referral_code

Prerequisite

Global Attributes are available from NVECTA iOS SDK v8.0.0 onwards. Upgrade to 8.0.0 or later before using the methods on this page.

This guide also assumes you're familiar with System Events and Custom Events. If not, start with the Tracking Events guide.

Which events they apply to

Once set, global attributes are automatically included on:

• All Custom Events you track with the trackEvents() method
• Automatically captured system events, such as install, update, app_launch, and session_start

Availability

Global Attributes are supported on Web, Android, and iOS. This page covers the iOS SDK; the Web and Android SDKs expose the same capability through their own methods.

Step 1 — Configure the persistence mode

Before using Global Attributes, configure the persistence mode in your app's AppDelegate. Do this before calling NVECTA's initialize() method, so the SDK can initialize and manage Global Attributes correctly.

NVECTA supports three persistence modes:

• Memory stores attributes only while the app process is alive.
• Session keeps attributes for the current app session and clears them automatically when the session ends.
• Persistent is the only mode that stores attributes on the device, so they remain available after the app is closed or restarted.

Syntax

notifyvisitors.globalAttributesPersistenceOptions(persistenceType: nvGlobalAttributePersistenceType, expiryInDays: Int)

[notifyvisitors globalAttributesPersistenceOptions:(nvGlobalAttributePersistenceType)persistenceType
                                      expiryInDays:(NSInteger)expiryInDays];

expiryInDays applies only to Persistent mode

Use 0 for Memory and Session modes.

Example

// Memory
notifyvisitors.globalAttributesPersistenceOptions(persistenceType: .memory, expiryInDays: 0)
notifyvisitors.initialize(nvMode)

// Session
notifyvisitors.globalAttributesPersistenceOptions(persistenceType: .session, expiryInDays: 0)
notifyvisitors.initialize(nvMode)

// Persistent
notifyvisitors.globalAttributesPersistenceOptions(persistenceType: .persistent, expiryInDays: 10)
notifyvisitors.initialize(nvMode)

// Memory
[notifyvisitors globalAttributesPersistenceOptions:nvGlobalAttributePersistenceTypeMemory expiryInDays:0];
[notifyvisitors initialize:nvMode];

// Session
[notifyvisitors globalAttributesPersistenceOptions:nvGlobalAttributePersistenceTypeSession expiryInDays:0];
[notifyvisitors initialize:nvMode];

// Persistent
[notifyvisitors globalAttributesPersistenceOptions:nvGlobalAttributePersistenceTypePersistent expiryInDays:10];
[notifyvisitors initialize:nvMode];

Step 2 — Setting global attributes

Use this method to define the Global Attributes that should be included with your events.

Syntax

notifyvisitors.setGlobalAttributes(_ attributes: [String: Any])

[notifyvisitors setGlobalAttributes:(NSDictionary<NSString *, id> *)attributes];

Example

notifyvisitors.setGlobalAttributes(["campaign_id": "SUMMER_2026",
                                    "membership_plan": "Premium"])

[notifyvisitors setGlobalAttributes:@{@"campaign_id": @"SUMMER_2026",
                                      @"membership_plan": @"Premium"}];

After setting the above Global Attributes, both auto-captured and custom events will automatically include:

{
   "campaign_id": "SUMMER_2026",
   "membership_plan": "Premium"
}

• If you define Global Attributes in the AppDelegate before calling initialize(), they are automatically attached to system events such as install, update, app_launch, and session_start. Defining them during application startup ensures these events include the required attributes and prevents them from being missed.
• You can also call this method from anywhere in your application to add, update, or overwrite Global Attributes for subsequent events.

Updating global attributes

Use setGlobalAttributes() to add new Global Attributes or update the values of existing ones.

notifyvisitors.setGlobalAttributes(["membership_plan": "Gold"])

[notifyvisitors setGlobalAttributes:@{@"membership_plan": @"Gold"}];

Only the specified attributes are added or updated. Any existing Global Attributes that are not included in the request remain unchanged.

Removing global attributes

Remove a single attribute by key with removeGlobalAttribute():

notifyvisitors.removeGlobalAttribute(forKey: "campaign_id")

[notifyvisitors removeGlobalAttributeForKey:@"campaign_id"];

The removed attribute will no longer be included in future events.

Clear all Global Attributes with clearGlobalAttributes():

notifyvisitors.clearGlobalAttributes()

[notifyvisitors clearGlobalAttributes];

After clearing, none of the previously defined Global Attributes will be attached to future events.

Good to know

• Global Attributes are best suited for values that should be sent with multiple events, such as attribution data, experiment IDs, user context, or checkout information.
• If an attribute is relevant to only a single event, pass it directly in the attributes parameter of the trackEvents() method instead.
• Use distinct names for global attributes and event attributes to keep your data clean and unambiguous.