Custom events

Trigger custom events for user behavior not covered in Copilot 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.
Provider Group - Should be one of the predefined provider groups. Possible values are All, Engagement, Main, DevSupport.
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 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 provider the Event name, screen name, provider group 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
Provider group: All
Custom event properties :
- spaceship_destination = earth
- days_of_travel = 3

Implementation of the event will look as below:

Event setup

iOS

Android

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
    }
    
    var eventGroups: [AnalyticsEventGroup] {
        return [.All]
    }
}

@Grouping(groups = {ProviderGroup.All})
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;
   }
}

Dispatching the event

iOS

Android

Copilot.instance.report.log(event: TapSpaceshipLaunchAnalyticsEvent(spaceshipDestination: "earth", daysOfTravel: 3))

Copilot.getInstance().Report.logEvent(new TapSpaceshipLaunchAnalyticsEvent("earth",3));