The Mobile app messaging SDKs for iOS and Android send events to the MCE servers to indicate that certain actions have happened related to your mobile app. Some of these events get translated into Universal Behaviors (UBs) that are sent to the Acoustic Campaign servers.

These events are all treated the same within the MCE system and generate an API call that gives a metric, or report. A metric is something that is counted and recorded, and metrics are available for mobile app messages. Events are not generated internally for sending mobile app messages because the server sends a large amount. When the MCE server is finished handling the event, it is passed to the Acoustic Campaign translation layer, which is a piece of the system that knows how to transform each event it receives into a Universal Behavior. The translation layer forwards it to Acoustic Campaign through their APIs. Of all of the events that are received, only a well-defined subset are recognized and forwarded to Acoustic Campaign.

All Universal Behaviors are supported immediately in both the SDK and the Acoustic Campaign user interface. The system automatically adds available Universal Behavior events to Queries, Programs, and Scoring for a Mobile Push-enabled database in organizations. Available events depend on your mobile app settings, which you configure.For more information about Universal Behaviors in Acoustic Campaign, see Universal Behavior Events for Mobile App Messages.

Note: Acoustic Campaign documentation contains information for marketers, app developers, and organization administrators and requires a user name and password. If you need a user name and password, contact your Client Services representative.

The following Universal Behaviors are available in Acoustic Campaign:

  • Mobile App – Installed  – SDK initiated
  • Mobile App – Uninstalled – Server initiated
  • Mobile App – Started a session  – SDK initiated
  • Mobile App – Ended a session – SDK initiated
  • Mobile App – Been sent a mobile app message (Available only in Queries and in the Rulebuilder) – Server initiated
  • Mobile App – Opened a mobile app message – SDK initiated
  • Mobile App – Performed a custom event – SDK initiated
  • Mobile App – Enabled mobile app messages – SDK initiated
  • Mobile App – Disabled mobile app messages – SDK initiated

Mobile App – Uninstalled and Mobile App – Been sent a mobile app message are sent without the SDK due to server-only information. Mobile App – Uninstalled is sent when the MCE server gets back from the Apple or Google servers that the device token is no longer valid. Mobile App – Been sent a mobile app message is when a push is sent, and before it is received by the SDK; however, it is unknown whether the message will be received.

Any mobile app message that is opened sends an event to the MCE server, and the server communicates that event to Acoustic Campaign. The attributes of the event include which type was sent and what the value was; for example, type=dial and value=3420948209.

Currently, events are not strictly defined.

"type" : "simpleNotification",
"name" : "appOpened",
... // other fields

Because Acoustic Campaign rejects any Universal Behavior that it does not recognize, a custom Universal Behavior is available to allow other events to reach their system. If you want to send custom events that are not included in the user interface, the type value must be custom to send a custom Universal Behavior. The name value is then translated into actionTaken in the Universal Behavior. If the following keys are included in the arguments list, they will also be included in the custom Universal Behavior: customData1, customData2, customData3, and otherCustomData.

The following Android code example shows an event created:

List attributes = new LinkedList();
attributes.add(new StringAttribute("payload", "{\"customData1\":\"exampleEvent\", 
\"customData2\":" + openForAction + ", \"customData3\":" + sendCustomEvent));

Event event = new Event(Constants.Notifications.SIMPLE_NOTIFICATION_EVENT_TYPE, 
"custom", new Date(), attributes, "example", mailingId);

MceSdk.getQueuedEventsClient().sendEvent(getApplicationContext(), event);

The following iOS code example shows an event created.

MCEEvent * event = [[MCEEvent alloc]init];
event fromDictionary:@{ @"timestamp":[NSDate date],@"type":@"custom", @"name":@"should end up in actionTaken", @"attributes":@ {@"customData1":@"should be in customData1", @"customData2":@"should be in customData2", @"customData3":@"should be in customData3", @"otherCustomData":@"should be in otherCustomData" } }]; [[MCEEventService sharedInstance] addEvent:event immediate:TRUE];

These events send the following Universal Behavior to Acoustic Campaign:

{"name":"actionTaken","value":"should end up in actionTaken"},
{"name":"customData1","value":"should be in customData1"},
{"name":"customData2","value":"should be in customData2"},
{"name":"customData3","value":"should be in customData3"},
{"name":"otherCustomData","value":"should be in otherCustomData"}]}]} 


Triggers for UBs

Mobile App – Uninstalled: The uninstalled event is generated is by using the APNs Feedback service, which is queried periodically. APNs should only provide tokens for truly uninstalled applications that have failed to receive a mobile app message and not for opted out mobile app messages. When the mobile app user is asked to opt in to mobile app messages, even if the mobile app user denies that their device will still receive silent messages. This is useful to update settings on the device and even add in-app messages. The uninstall must happen, then a push, and then the feedback service; at that point, the uninstalled UB is sent. On Android, the uninstall event is triggered when a mobile app message is sent and the mobile app is no longer installed. Unlike iOS, this feedback is immediate during the push process.

Mobile App – Enabled mobile app messages and Mobile App – Disabled mobile app messages: For iOS, UBs are sent out after the preference is changed and the mobile app is launched again. Android apps get the notification that the preference has changed when the mobile app user sets it.

Mobile App – Installed gets triggered when the application is started for the first time.

Mobile App – Started a session: With a default 20-minute timeout if the mobile app is started, the mobile app is moved to the background and brought to the foreground within 20 minutes; this is considered a single session.

Mobile App – Ended a session: When the mobile app leaves the foreground in iOS, it records that in its preferences. The next time that the mobile app starts, it checks the last time that a session started. If it is over 20 minutes, it will end the previous session, which sends the UB, and start a new session. Android does all this with a service and sends that the session ended when it literally ends and does not wait for the mobile app to be started again before sending it.

Mobile App – Opened a mobile app message: This UB is fired whenever a notification is opened. It does not matter which action is performed after the app opens; this UB will be sent. It also will include the action that was fired in it, but it does not have to be a specific type of action to get the UB.

Go Back to the Mobile App Messaging home page.

7 comments on"Advanced universal behaviors (UB)"

  1. Where we need to see the “custom event data” in WCA dashboard

    • JoanGriffin June 22, 2017

      Custom event data can be viewed on the Query Summary page in WCA. The WCA dashboard provides information about only reporting and support.
      To see custom event data, you need to create and run a query (Content > Queries). When creating the query, ensure that you select Universal Behaviors and the custom event option. Finally,
      open the Query Summary page to see custom event data that is based on the query criteria.
      For more information about the WCA dashboard, contact the Support Portal at

  2. We have successfully created the query….
    But still We can’t check the expected result.
    1. If we construct a query, based on NAME, we get the expected result.
    2. If we construct a query, based on CustomData1 / CustomData2 / CustomData3/ otherCustomData, we can’t see any result

    Sample format :

    • JoanGriffin July 10, 2017

      Hi Venkat,
      we are researching your question.

    • JoanGriffin July 10, 2017

      Hi Venkat,
      It could be that there are no customers in the database that satisfy the 4 custom data criteria… are you using “and” or “or”?

  3. I just want to understand if there is a way to identify a record in the WCA push database as being a push enabled record (other than via the presence of an MU-ID.

  4. The MU-ID is a normal field which can be updated via the API so if this field is updated on a non-push enabled record, we wouldn’t be able to tell the difference.

Join The Discussion

Your email address will not be published. Required fields are marked *