Custom events

Custom Events

Trigger custom events for user behavior not covered in Copilot.cx predefined events. When implementing custom events, please be sure to include the relevant properties as described below:

  • Event name - The custom event’s name.
  • Screen Name - The screen name on which the event was triggered, as perceived by the user. If the event origin is not a user, sending the screen name on which the event was triggered is not required.
  • Event Origin - The origin of the event. Possible values are User/Server/App/Thing.
  • Custom event properties - Additional data that is relevant for the specific event.

💡Custom event properties should be identical between platforms (iOS/Android).

Standard custom event properties

There's a set of standard custom event properties that can be added to your custom event. The value of these properties will be taken into account in Copilot.cx audience selection to exclude users for specific campaigns or to include them in others:

  • is_fault - A boolean property that will be used to indicate that the event represents a fault the user experienced. In order to integrate this property add to the custom event properties the following key : is_fault with true or false value.

💡This property is optional - Event that do not has this property will be treated as is_fault=false

Dispatching custom events

In order to dispatch custom event please extend the AnalyticsEvent base class/protocol and provide the Event name, screen name, and event origin. Please follow the example below:

Example

In case we would like to create new event that will be triggered when the user Jor-el pressed a key to launch the Kal-El’ spaceship to earth, requested journey length is 3 days. This action is triggered and executed directly by the User on the SpaceshipReadyForLaunchScreen.

  • Event name : tap_spaceship_launch
  • Screen name : spaceship_ready_for_launch_screen
  • Event origin : User
  • Custom event properties :
    • spaceship_destination = earth
    • days_of_travel = 3

There are two different alternative ways to configure and dispach custom events:

1. Creating an inline instance of CustomAnalyticsEvent


Setting up and dispatching the event

Copilot.instance.report.log(event: CustomAnalyticsEvent(eventName: "TapSpaceshipLaunched", customParams: [
                "screen_name": "spaceship_ready_for_launch_screen",
                "days_of_travel": "3",
                "spaceship_destination": "earth"
            ]));
Copilot.getInstance().Report.logEvent(new CustomAnalyticsEvent("TapSpaceshipLaunched", new HashMap<String, String>(){{
                put("screen_name", "spaceship_ready_for_launch_screen");
                put("days_of_travel", "3");
                put("spaceship_destination", "earth");
            }}));
Copilot.getInstance().Report.logEvent(CustomAnalyticsEvent("TapSpaceshipLaunched", hashMapOf(
            "screen_name" to "spaceship_ready_for_launch_screen",
            "days_of_travel" to "3",
            "spaceship_destination" to "earth"
        )))

2. Implementing the AnalyticsEvent protocol/interface

Event setup

import CopilotCX

struct TapSpaceshipLaunchAnalyticsEvent: AnalyticsEvent {
    
    private let spaceshipDestination: String
    private let daysOfTravel: Int
    
    init(spaceshipDestination:String, daysOfTravel :Int) {
        self.spaceshipDestination = spaceshipDestination
        self.daysOfTravel = daysOfTravel
    }
    
    var customParams: Dictionary<String, String> {
        return ["spaceship_destination" : spaceshipDestination,
                "days_of_travel" : String(daysOfTravel),
                "screenName" : "spaceship_ready_for_launch_screen"]
    }
    
    var eventName: String {
        return "tap_spaceship_launch"
    }
    
    var eventOrigin: AnalyticsEventOrigin {
        return .App
    }
}
public class TapSpaceshipLaunchAnalyticsEvent extends AnalyticsEvent {

   @CustomEventParameter("spaceship_destination")
   private String mSpaceshipDestination;

   @CustomEventParameter("days_of_travel")
   private int mDaysOfTravel;

   protected TapSpaceshipLaunchAnalyticsEvent(String spaceshipDestination, int daysOfTravel) {
       super("tap_spaceship_launch", "spaceship_ready_for_launch_screen");
       mSpaceshipDestination = spaceshipDestination;
       mDaysOfTravel = daysOfTravel;
   }

   @Override
   public EventOrigin getEventOrigin() {
       return EventOrigin.User;
   }
}
class TapSpaceshipLaunchAnalyticsEvent(
    @field:CustomEventParameter("spaceship_destination") private val mSpaceshipDestination: String,
    @field:CustomEventParameter("days_of_travel") private val mDaysOfTravel: Int
): AnalyticsEvent("tap_spaceship_launch", "spaceship_ready_for_launch_screen") {
    override fun getEventOrigin(): EventOrigin = EventOrigin.User
}

Dispatching the event

Copilot.instance.report.log(event: TapSpaceshipLaunchAnalyticsEvent(spaceshipDestination: "earth", daysOfTravel: 3))
Copilot.getInstance().Report.logEvent(new TapSpaceshipLaunchAnalyticsEvent("earth",3));
Copilot.getInstance().Report.logEvent(TapSpaceshipLaunchAnalyticsEvent("earth",3))
← Predefined eventsReleases →