Activities

Overview

Apps in Wix work together by sharing information about site visitor activity. An activity is a visitor’s interaction with the site, such as filling out a contact form, making a purchase, or sharing a page from the site on social media.

You’ll use the WixHive to request information that’s useful for your app, and also post information that your app collects.

Activities are tracked by a visitor’s email, phone, or cookie. If a site visitor is a Contact, you will be able to link between the Contact and its Activities.

Read more about the different activity types and their schemas below.

How Does it Work?

When you register your app in the dev center, you can sign up to receive or post Activities about different events that happens within the website, according to your product needs.

  • Post an Activity to report about events that occurred within your app.
  • Get an Activity when it was reported to trigger an action within your app.
Post Activity

When posting an Activity to Wix, make sure the data conforms to the specific schema for that type of Activity, so that other apps know what to expect when receiving it. Each type of Activity has its own schema, represented in JSON schema format.

Activities are connected to a session, which is a cookie stored in the site visitor’s browser. This means that when you (or another app) post Activities from the same browser session, they are all linked to the same site visitor. If the site visitor is a Contact, all Activities connected to this session are linked to the Contact, even Activities posted before the Contact was created.

 How to post an Activity

Use the Wix.Activities.postActivity SDK method.

You can see the full list of parameters in the method documentation, but here’s a quick look at the most important parameters:

  • activity.Info: Build this object using the correct activity schema.  Refer to the list of activities and their schemas.  
  • contactUpdate: Add any information your app has about the site visitor (such as email, phone, or name) in the contactUpdate object. This object links the Activity to a Contact.
  • details.additionalInfoUrl: When an important activity is posted, we display a notification in the site’s dashboard. Users can click on this notification to see more information about the activity, so define this URL when you post the activity. (Check out the section below – “What happens in the site’s dashboard when you post an activity” for more details.)

What happens in your app when you post the activity

Once you post the activity, you’ll receive the Activity ID immediately. If you used the contactUpdate object, we’ll check if the Contact exists for this browser session:

  • If a Contact already exists for this session, we’ll add the new information you provided to this Contact and send you the Contact ID.
  • If this Contact doesn’t exist yet, we’ll create a new Contact and send you its ID. All Activities connected to this specific session will be linked to the new Contact.

What happens in the site’s dashboard when you post an activity

You can use the points below as a quick check to make sure you implemented the WixHive correctly.

If you provided the site visitor’s email/phone number when you posted the activity, we’ll link the activity to a contact and show the new information to users. Here’s what users will see in the site’s dashboard – and what you should see when testing the WixHive in your app:

  • A notification for important activities: Users can click on this notification to see more information about the activity. You can direct users to a URL with more information – use the additionalInfoUrl parameter in the postActivity method.

    We display notifications for these activities:

    • Form activities (contact-form, subscription-form, form)
    • Scheduler appointment activity
    • eCommerce purchase activity
    • Hotels reservation activity
    • Social track activity

Note: If you think it’s important for us to notify users about an activity posted by your app, let us know!

  • A new message in the Wix Engage app: Users can see important activities that happened in their site – whether it’s done by an existing contact or an anonymous site visitor. (You can see the full list of important activities, above.)
  • New information about site visitors: When users go to the contact’s page, they can see the activity you posted, as well as any new information you sent about the contact. If the site visitor is a new contact, users will see the new contact in the contacts section of the dashboard.
    (You’ll add this information in the contactUpdate parameter in the postActivity method.)
Note: Activities that are not linked to a Contact will not be visible to users.
Get Activity

When you register your app, you can sign up to receive immediate notification when an Activity occurs. These events will be delivered to your app via webhooks and will include the Activity ID. To get the Activity data use the HTTP API or the JavaScript SDK with the relevant Activity ID.

There will be times when your app needs to get a list of Activities that have already occurred on a site. In such cases, you can request these Activities through our JavaScript SDK or through our HTTP API, as shown below.

You can use parameters to filter your search:

  • Use the from and until parameters to retrieve Activities by creation time.
  • Set the scope parameter to app to get Activities that were created by your app. Set the scope parameter to site to get Activities that were created by all apps on a site. Default is site.
  • Use the activityTypes parameter to filter by the type of Activity.

Activity Schemas

The Activities listed below can be posted by your application to report about events that occurred within your app.

Forms

Use the following activities for form events in your app:

  • Contact-Form: when your app submits a contact form.
  • Subscription-Form: when your app submits a subscription from.
  • Form: when your app submits another type of form, like a survey.

You’ll add the site visitor’s details (name, email, etc) in the contactUpdate object, and not in the form activity itself (see more information on posting an activity). So there’s no need to post form fields that ask for these details.

Contact-Form

NameTypeDescription

Example:

Subscription-Form

NameTypeDescription

Get the Subscription-Form Activity JSON.

Example:

Form

NameTypeDescription

Example:


Get the Form activity JSON.

Scheduler

Use the following activities for scheduling events that occur in your app:

  • Appointment: when an appointment is made.
  • Cancel: when an appointment is cancelled.
  • Confirmation: when an appointment is confirmed.

Appointment and Confirmation

PropertyTypeDescription

Cancel

PropertyTypeDescription

Get the Cancel Appointment Activity JSON.

Example

 

 

Social

Use the following activities to track social actions that occur in your app – for example, when a site visitor comments on the site, likes an Instagram photo, or posts a comment through Facebook:

  • Comment: when a site visitor posts a comment on the site – whether the comment is posted on the site only, or also posted to the visitor’s social media page through a plugin on the site.
  • Share-url: when a site visitor shares an item (like a blog post or photo) on social media.
  • Track: when a site visitor takes one of these social media actions on the user’s channel: like, follow, subscribe, pin.

Comment

PropertyTypeDescription

Example:

Share-url

PropertyTypeDescription

Track

PropertyTypeDescription

Hotels

Use the following activities for hospitality events in your app:

  • Purchase: When a site visitor purchases a service offered by the hotel.
  • Purchase-Failed: When the purchase of a hotel service could not be completed.
  • Reservation: When a site visitor reserves a hotel room.
  • Confirmation: When a reservation is confirmed.
  • Cancel: When a reservation is canceled.

Purchase

PropertyTypeDescription

Example:

Purchase-failed

PropertyTypeDescription

Example:

Confirmation and Reservation

PropertyTypeDescription

Get the Confirmation and the Reservation Activity JSON.

Cancel

PropertyTypeDescription

Example:

 

Music

Use the following activities for music events in your app:

  • Track-Play: When a request to start playing a song is made
  • Track-Skip: When a track was skipped
  • Track-Played: When a song has completed its run
  • Track-Lyrics: When the track lyrics are requested
  • Track-Share: When a track is shared using the app
  • Album-Share: When an album is shared through your app
  • Album-Fan: When a visitor becomes a fan of an album
  • Album-Played: When an album has completed its run

Track-Play, Track-Skip, Track-Played, and Track-Lyrics

Property TypeDescription

Get the Track-Play, Track-Skip, Track-Played, and Track-Lyrics Activity JSON.

Track-Share

Property TypeDescription

Example:

Album-Share

Property TypeDescription

Example:

 

Album-Fan and Album-Played

Get the Album-Fan and the Album-Played Activity JSON.

eCommerce

Use the following activities for eCommerce events in your app:

  • Cart-add: An item was added to the cart.
  • Cart-remove: An item was removed from the cart.
  • Cart-abandon: A cart with these items was abandoned.
  • Cart-checkout: A checkout process has begun with this cart.
  • Purchase: The checkout process has completed.
Does your app rely on getting eCommerce activities that happened in the site? Keep in mind that Wix’s eCommerce app, WixStores, currently posts only the purchase activity.

Cart-add and Cart-remove

PropertyTypeDescription

Get the Cart-add JSON and the Cart-remove JSON.

Cart-abandon and Cart-checkout

PropertyTypeDescription

Purchase

 
PropertyTypeDescription

Example

 

Messaging

Use the following activity for chat and other messaging events in your app:

  • im: when a chat/sms message is sent between a Wix user and a site visitor/contact.

im

PropertyTypeDescription

Get the im activity JSON.

Example

Events

Use the RSVP activity for RSVPs to events created by Wix users (like conferences, webinars, or parties).

RSVP

PropertyTypeDescription

Example

Deprecated
  • The EVENTS_EVENT_UPDATE activity is now deprecated. Use the updated RSVP activity instead.
  • The CONTACT_CONTACT_FORM activity is deprecated. Use the updated contact-form activity or our new form activity (for other types of forms), instead.
  • The CONTACT_SUBSCRIPTION_FORM activity is now deprecated. Use the updated subscription-form activity instead.
  • The SEND_MESSAGE activity is deprecated. Use the IM activity instead.

Was this page helpful?

What can we do to improve it?

What did you like about it?