A trigger is an event that causes an automation to run. In general, this can be any event that occurs on a user’s site or site dashboard, such as a visitor landing on a particular site page, or the site owner creating an invoice.
If you’re an app developer, you can turn events associated with your app into triggers. For example, if your app provides rental services to Wix sites, a customer requesting to rent an item is an event associated with your service. You can choose to turn this event into a trigger by reporting it to Wix. In short, events occur all the time in your service, but they only become triggers if you report them.
Once you decide to turn an event in your service into a trigger, the first thing you need to do is add a trigger extension to your app in the app dashboard. When you set up your trigger extension, you can add several different configuration options. These options allow you to better tailor your trigger’s functionality to user needs.
You’re required to configure a payload schema, which defines the fields your event passes to Wix when it gets reported. Optionally, you can add any of the following configurations to your trigger:
In the following sections, we’ll go over each of these options so you understand what they do and how they can benefit the users who add your trigger to their automations.
When your app reports an event, it passes a payload of event data to Wix. The payload schema tells Wix exactly what data to expect.The payload schema is a JSON schema that defines the data fields sent to Wix. You’re required to create this schema when you configure your trigger in the app dashboard. The schema defines each field as a property that has one of the following data types:
The payload schema is the only part of the trigger configuration that is mandatory. To learn how to create a payload schema for your trigger, see the Trigger payload schema.
By default, triggers activate immediately when an event occurs. This is known as a real-time event, and doesn’t require any extra configuration on your part when you set up the trigger.
Sometimes, however, an event is scheduled for a certain time, and a user needs the trigger to activate prior to that time. A good example is a reminder for an appointment. It doesn’t help if a reminder is sent in real-time when the appointment starts. It needs to be sent prior to the start of the appointment.
By configuring scheduled triggers, you allow a trigger to activate prior to the start of the actual event. If you add this configuration, it gives users more control over when they can run their site automations. Without trigger scheduling, a user can only set an automation to run immediately or after the event occurs (using action delays). With trigger scheduling, a user has the option to run automations before, after, or immediately when the scheduled event occurs. For example, a user can trigger an automation to send a reminder to a customer two days before a session starts.
You can allow trigger scheduling by adding an annotation to the payload schema.
Many of the events in your app occur because of actions taken by a person on a site, either a site owner or a site visitor. It’s useful and often necessary to retrieve the contact data for that particular person.
When you configure your payload schema in the app dashboard, you can select one of the payload properties to connect to a contact ID. This tells Wix to do two things:
For example, let's say this is your initial payload format:
You decide to connect the customerId property to a contact ID. When your event is reported, Wix fetches the contact data for the customer ID and adds it under the connected property. It looks like this:
Connecting a payload property to a contact ID gives users access to the related contact information (such as name, emails, or phone numbers) in their automation actions. It also allows them to trigger contact-based actions like Send an email. Not connecting a contact ID limits the actions a user can combine your trigger with.
Normally, a trigger activates an automation every time the event is reported. For example, a trigger called Product purchased activates its automation every time a customer purchases a product from an online store.
However, the user may only want to trigger an automation when customers purchase specific products. To give users the option to selectively trigger automations, you can set up filter fields for your trigger when you configure it in the app dashboard.
Filter fields allow users to set conditions on specific fields in the event payload. If those conditions are met when your app reports an event, then the automation activates. However, if one or more of the payload fields fail to meet the conditions the user set, the automation doesn’t run.
For example, let’s say you create the Product purchased trigger as part of your app. Imagine it has a very simple payload schema that looks like this:
A site owner installs your app, and wants to connect your trigger to an action called Send a coupon. However, the site owner only wants to activate the automation if the purchaser is a returning customer who buys at least $50 worth of items.You can enable the site owner to do this by configuring filter fields on isPreviousCustomer and purchaseAmount. With those filter fields configured, the user can set Product purchased to only activate the automation when isPreviousCustomer is true and purchaseAmount is greater than $50.
There are several types of filter fields available:
It’s not enough to just set up the trigger extension in the app dashboard; you also need to report your event to Wix. If you don’t, Wix won’t recognize when your service events occur and your triggers won’t run any automations.
To report your service event, you call the Report Event method as part of your logic to handle the event.
When you call Report Event, you pass it a payload of data from the event. This payload should match the schema you defined in the app dashboard. For example, if your payload schema looks like this:
Then the payload you pass to Report Event might look like this:
Below is an example of a call to Report Event:
Once your app is installed and active on a site, it reports the event to Wix every time the event occurs. Wix makes it available as a trigger to any users who have installed your app. Users can then create automations with your trigger.
For a step-by-step guide on how to set up your trigger in the app dashboard, see Add a Trigger to your App.