Send events via SDKs

If you're not yet confortable with the "SDK" notion, don't hesitate to consult the Implementation methods article.

Our SDKs offer methods to manage properties and send events.

Tagging methods

The main method you will use is to send an event with properties.

Javascript

Method: pa.sendEvent(eventName[, eventData, options])

Parameters	Type	Description
eventName	string	Name of the event
eventData (optional)	object	Object of properties
options (optional)	object	Object of options
options.onBeforeBuild(PianoAnalytics, model, next)	function	Callback plugged before the event is built. PianoAnalytics is the tracker reference, model is the model of the event, next calls the next step
options.onBeforeSend(PianoAnalytics, model, next)	function	Callback plugged before the event is sent. PianoAnalytics is the tracker reference, model is the model of the event, next calls the next step

pa.sendEvent('page.display', {
  'page': 'Page name',
  'page_premium': false,
  'page_authors': ['Clark Kent', 'John Cena']
});

In the following example, we are updating the site ID for the current event:

pa.sendEvent('page.display', {
  'page': 'Page name',
  'page_premium': false,
  'page_authors': ['Clark Kent', 'John Cena']
},{
  onBeforeBuild: function (PianoAnalytics, model, next) {
    model.setConfiguration('site','123456789');
    next();
  },
});

You can also send several events using one method:

Method: pa.sendEvents(eventsArray[, options])

Parameters	Type	Description
eventsArray	array	Array of event objects
options (optional)	object	Object of options
options.onBeforeBuild(PianoAnalytics, model, next)	function	Callback plugged before the event is built. PianoAnalytics is the tracker reference, model is the model of the event, next calls the next step
options.onBeforeSend(PianoAnalytics, model, next)	function	Callback plugged before the event is sent. PianoAnalytics is the tracker reference, model is the model of the event, next calls the next step

pa.sendEvents([ 
  {
    'name': 'page.display',
    'data': { ... } 
  },{
    'name': 'page.scroll',
    'data': { ... } 
  }
]);

Android

Methods:

func PianoAnalytics.sendEvent(event) -> void

func PianoAnalytics.sendEvent(event,config) -> void

func PianoAnalytics.sendEvent(event,config,l) -> void

Parameters	Type	Description
event	Event	Event to send
Event.name	String	Event name
Event.data	Map	Event properties
config	Configuration	Configuration object
l	OnWorkListener	Hooks on specific steps

pa.sendEvent(new Event("page.display", new HashMap<String, Object>() {{
  put("page", "Page name");
  put("page_premium", false);
  put("page_authors", new String[]{"Clark Kent", "John Cena"});
}}));

A more advanced example:

pa.sendEvent(
  new Event("page.display", new HashMap<String, Object>() {{
  put("page", "Page name");
  put("page_premium", false);
  put("page_authors", new String[]{"Clark Kent", "John Cena"});
  }}),
  new Configuration.Builder().withSite(123456789).build(),
  new PianoAnalytics.OnWorkListener() {
    @Override
    public boolean onBeforeBuild(Model model) {
      // add custom actions here
      return true;
    }

    @Override
    public boolean onBeforeSend(BuiltModel built, Map<String, BuiltModel> stored) {
      // add custom actions here
      return true;
    }
  }
);

You can also send several events using one method:

Method:

func PianoAnalytics.sendEvents(events) -> void

func PianoAnalytics.sendEvents(events,config) -> void

func PianoAnalytics.sendEvents(events,config,l) -> void

Parameters	Type	Description
events	Event[]	Event to send
Event.name	String	Event name
Event.data	Map	Event properties
config	Configuration	Configuration object
l	OnWorkListener	Hooks on specific steps

pa.sendEvents(Arrays.asList(
    new Event("page.display", new HashMap<>(...)),
    new Event("page.scroll", new HashMap<>(...))
));

Apple

Method: pa.sendEvent(_ event: Event, config: Configuration? = nil, p: PianoAnalyticsWorkProtocol? = nil)

Parameters	Type	Description
event	Event	Event to send
Event.name	String	Event name
Event.data	[String: Any]?	Event properties
config	Configuration?	Configuration object
p	PianoAnalyticsWorkProtocol?	Hooks on specific steps

pa.sendEvent(Event("page.display", data: [
  "page": "Page name",
  "page_premium": false,
  "page_authors": ["Clark Kent", "John Cena"]
]))

A more advanced example:

class PianoAnalyticsCustomProtocol: PianoAnalyticsWorkProtocol {
  func onBeforeBuild(model: inout Model) -> Bool {
      // add custom actions here
      return true
  }

  func onBeforeSend(built: BuiltModel?, stored: [String: BuiltModel]?) -> Bool {
      // add custom actions here
      return true
  }
}

pa.sendEvent(
  Event("page.display", data: [
    "page": "Page name",
    "page_premium": false,
    "page_authors": ["Clark Kent", "John Cena"]
  ]),
  config: ConfigurationBuilder().withSite(123456789).build(),
  p: PianoAnalyticsCustomProtocol()
)

You can also send several events using one method:

Method: pa.sendEvents(_ events: [Event], config: Configuration? = nil, p: PianoAnalyticsWorkProtocol? = nil)

Parameters	Type	Description
events	[Event]	Event to send
Event.name	String	Event name
Event.data	[String: Any]?	Event properties
config	Configuration?	Configuration object
p	PianoAnalyticsWorkProtocol?	Hooks on specific steps

pa.sendEvents([
    Event("page.display", data: [...]),
    Event("page.scroll", data: [...])
])

tip

In your Data Model, a property is tied to a specific type. When you tag your properties, this type must be the same.

The JSON type is automatically assigned to the property. If you want to assign a specific type to a property, please consult the dedicated ressource in our Collection API article.

Add properties to events

You can add properties to subsequent events, by using specific methods.

Add one property to subsequent events

Javascript

Method: pa.setProperty(propertyName, propertyValue[, options])

Parameters	Type	Description
propertyName	string	Name of the property
propertyValue	string, number, boolean, array (string, boolean, number)	Value of the property
options (optional)	object	Options
options.persistent	boolean	Indicates whether the property should be sent on all subsequent events (true) or just the next event sent (false - default)
options.events	string, array	Event names the property will be sent on (all events by default)

pa.setProperty('page_premium', false, {
  'persistent': true,
  'events': ['page.*', 'click.navigation']
});

This example sends page_premium property with the value false on all subsequent page.* and click.navigation events.

Android

Method:

func PianoAnalytics.setProperty(key, value) -> void

func PianoAnalytics.setProperty(key, value, persistent) -> void

func PianoAnalytics.setProperty(key, value, persistent, events) -> void

Parameters	Type	Description
key	String	Name of the property
value	Object	Value of the property
persistent	Boolean	Indicates whether the property should be sent on all subsequent events (true) or just the next event sent (false - default)
events	String[]	Event names the property will be sent on (all events by default)

pa.setProperty("page_premium", false, true, new String[]{"page.*", "click.navigation"});

This example sends page_premium property with the value false on all subsequent page.* and click.navigation events.

Apple

Method: pa.setProperty(key: String, value: Any, persistent: Bool = false, events: [String]? = nil)

Parameters	Type	Description
key	String	Name of the property
value	Any	Value of the property
persistent	Bool	Indicates whether the property should be sent on all subsequent events (true) or just the next event sent (false - default)
events	[String]?	Event names the property will be sent on (all events by default)

pa.setProperty(key: "page_premium", value: false, persistent: true, events: ["page.*", "click.navigation"])

This example sends page_premium property with the value false on all subsequent page.* and click.navigation events.

Add multiple properties to subsequent events

Javascript

Method: pa.setProperties(propertiesObject[, options])

Parameters	Type	Description
propertiesObject	object	Key value pairs of event name and event value
options (optional)	object	Options
options.persistent	boolean	Indicates whether the property should be sent on all subsequent events (true) or just the next event sent (false) (default: false)
options.events	string, array	Event names the property will be sent on (all events by default)

pa.setProperties({
  'page_premium': false,
  'page_authors': ['Clark Kent', 'John Cena']
}, {
  'persistent': true,
  'events': ['page.*', 'click.navigation']
});

This example sends page_premium and page_authors properties on all subsequent page.* and click.navigation events.

Android

Method:

func PianoAnalytics.setProperties(data) -> void

func PianoAnalytics.setProperties(data, persistent) -> void

func PianoAnalytics.setProperties(data, persistent, events) -> void

Parameters	Type	Description
data	Map	Properties to set
persistent	Boolean	Indicates whether the property should be sent on all subsequent events (true) or just the next event sent (false - default)
events	String[]	Event names the property will be sent on (all events by default)

pa.setProperties(new HashMap<String, Object>() {{
  put("page_premium", false);
  put("page_authors", new String[]{"Clark Kent", "John Cena"});
}}, true, new String[]{"page.*", "click.navigation"});

This example sends page_premium property on all subsequent page.* and click.navigation events.

Apple

Method: pa.setProperties(_ data: [String: Any], persistent: Bool = false, events: [String]? = nil)

Parameters	Type	Description
data	[String: Any]	Properties to set
persistent	Bool	Indicates whether the property should be sent on all subsequent events (true) or just the next event sent (false - default)
events	[String]?	Event names the property will be sent on (all events by default)

pa.setProperties([
  "page_premium": false,
  "page_authors": ["Clark Kent", "John Cena"]
], persistent: true, events: ["page.*", "click.navigation"])

This example sends page_premium property on all subsequent page.* and click.navigation events.