Custom Events
Custom events record any action specific to your app, with a name and attributes you choose. General rules for names, attributes and results: Sending Events.
Requirements
- A successful
ping()in this installation, see Contacts. - A stable event name and a fixed set of attribute names, see Naming rules.
Setup
Call sendEvent(name:attributes:_:) where the action happens:
- Swift
- Objective-C
UserSDK.default?.sendEvent(name: "subscription_started", attributes: [
"plan": "pro",
"billing_cycle": "annual",
"price": 99.99
]) { success, error in
if !success { print("Event failed: \(String(describing: error))") }
}
[[UserSDK default] sendEventWithName:@"subscription_started"
attributes:@{@"plan": @"pro", @"billing_cycle": @"annual", @"price": @99.99}
completion:^(BOOL success, NSError *error) {
if (!success) { NSLog(@"Event failed: %@", error); }
}];
Check
The event appears on the contact's timeline with its attributes. It can now be used in segments and automations.
Methods
sendEvent(name:attributes:_:)
Queues a custom event for the current contact. Renamed in 1.3.0: sendEvent(with:params:_:) still works and is deprecated until 2.0.
| Name | Type | Required | Description |
|---|---|---|---|
name | String | Yes | The event name. Use the same spelling and letter case every time. |
attributes | [String: Any]? | No | Event attributes, see Attribute value types. Default nil. |
completion | ((Bool, Error?) -> Void)? | No | Called with the result on the main thread. See Completion thread. |
Returns nothing. Without a contact (no successful ping yet), the completion reports notIdentified and the event is not queued. An invalid name or attribute value ends with invalidName or invalidData without a request. See Errors.
UserSDK.default?.sendEvent(name: "onboarding_completed")
Common errors
| Symptom | Cause | Fix |
|---|---|---|
Completion reports notIdentified ("No user exists yet") | No successful ping yet. | Call ping() first. |
| Some attributes are missing on the event | A value type differs from the first value sent for that attribute. | Keep each attribute's type stable. |
The event is missing, and after the retries the completion reports rejected(statusCode: 500) | The name was used before with different letter case. | Use one exact spelling. |