Vortex Events

type UUID = string & { _brand: 'UUID' };

type BaseEvent {
  organizationId: UUID; // id of the organization for which the event falls under
  accountId: UUID; // the id of the specific account within the organization for which the event falls under
  projectId: UUID; // the id of the specific project within the account for which the event falls under
  widgetConfigurationId: UUID; // the id of the widget configuration that originated the event or the underlying invitation associated with the event
  environmentId: UUID; // the id of the environment in which the event occurred
  deploymentId: UUID; // the id of the deployment specific to this event
  name: string; // the name of the event
  timestamp: Date; // the time which the event occurred
  platform: string; // the platform (web, ios, android) on which the invitation was initiated
  useragent?: string; // the useragent from of the device used to create the event if available
  referer?: string; // the full URL of the referer if available
  refererDomain?: string; // the domain of the referer if available.
  sessionId?: UUID; // the session id, generated by the widget, of a particular session.
  foreignUserId?: string; // the id, in your system, of the user that created the event, if available/applicable
  segmentation?: Record<string, any>; // segmentation of the event as specified by the widget prop
  payload?: Record<string, any>; // any unique information for the specific event type
  groups?: Array<{ // the group or groups that the event is related to as defined by your system
    type: string;
    id: string;
    name: string;
  }>; 
}

// Event Name: invite_sent
// Available via onEvent in Widget: false
// Event origins: This event is emitted by the vortex backend when an invitation is sent by us to an invitation target.
// Event Format:

type inviteSent extends BaseEvent {
  useragent?: 'vortex';
  referer?: null;
  refererDomain?: null;
  sessionId?: UUID; // the session id, generated by the widget for the session that created the invitation
  foreignUserId?: string; // the id, in your system, of the user that created the event, if available/applicable
  segmentation?: Record<string, any>; // segmentation of the event as specified by the widget prop
  payload?: {
    targets: { type: string; value: string }[]; // the invitation targets
    invitationId: UUID; // the invitation id associated with the event
  }
}

// Event Name: invite_click
// Available via onEvent in Widget: false
// Event origins: This event is emitted when an invitee clicks on any invitation link
// Event Format:

type inviteClick extends BaseEvent {
  useragent?: 'vortex';
  referer?: null;
  refererDomain?: null;
  sessionId?: UUID; // the session id, generated by the widget for the session that created the invitation
  foreignUserId?: 'anon-email'; // this event is associated with an anonymous user
  segmentation?: Record<string, any>; // segmentation of the event as specified by the widget prop at invitation creation time
  payload?: {
    targets: { type: string; value: string }[]; // the invitation targets
    invitationId: UUID; // the invitation id associated with the event
  }
}

// Event Name: invite_accept
// Available via onEvent in Widget: false
// Event origins: This event is emitted when an invitee accepts any invitation link
// Event Format:

type inviteAccept extends BaseEvent {
  useragent?: 'vortex';
  referer?: null;
  refererDomain?: null;
  sessionId?: UUID; // the session id, generated by the widget for the session that created the invitation
  foreignUserId?: 'anon-email'; // this event is associated with an anonymous user
  segmentation?: Record<string, any>; // segmentation of the event as specified by the widget prop at invitation creation time
  payload?: {
    targets: { type: string; value: string }[]; // the actual target that accepted the invitation (may differ from specified target)
    invitationId: UUID; // the invitation id associated with the event
  }
}

// Event Name: invite_reminder_sent
// Available via onEvent in Widget: false
// Event origins: This event is emitted when a reminder invitation is sent. This is done based on your configuration in Vortex
// Event Format:

type inviteReminderSent extends BaseEvent {
  useragent?: 'vortex';
  referer?: null;
  refererDomain?: null;
  sessionId?: UUID; // the session id, generated by the widget for the session that created the invitation
  foreignUserId?: string; // this event is associated with the user who created the invitation in your system
  segmentation?: Record<string, any>; // segmentation of the event as specified by the widget prop at invitation creation time
  payload?: {
    targets: { type: string; value: string }[]; // the invitation targets
    invitationId: UUID; // the invitation id associated with the event
  }
}

// Event Name: invite_nudge_sent
// Available via onEvent in Widget: false
// Event origins: This event is emitted when a nudge is sent. This is done based on your configuration in Vortex
// Event Format:

type inviteNudgeSent extends BaseEvent {
  useragent?: 'vortex';
  referer?: null;
  refererDomain?: null;
  sessionId?: UUID; // the session id, generated by the widget for the session that created the invitation
  foreignUserId?: string; // this event is associated with the user who created the invitation in your system
  segmentation?: Record<string, any>; // segmentation of the event as specified by the widget prop at invitation creation time
  payload?: {
    targets: { type: string; value: string }[]; // the invitation targets
    invitationId: UUID; // the invitation id associated with the event
  }
}

// Event Name: invite_send_error
// Available via onEvent in Widget: false
// Event origins: This event is emitted when there is a problem delivering an invitation.
// Event Format:

type inviteSendError extends BaseEvent {
  useragent?: 'vortex';
  referer?: null;
  refererDomain?: null;
  sessionId?: UUID; // the session id, generated by the widget for the session that created the invitation
  foreignUserId?: string; // this event is associated with the user who created the invitation in your system
  segmentation?: Record<string, any>; // segmentation of the event as specified by the widget prop at invitation creation time
  payload?: {
    error: string; // The error that was encountered. For instance, if you initially verified your domain with vortex and suddenly removed or altered the DNS entries, you might see an error here like "Domain is not verified. The following identities failed the check: yourdomain.com"
    invitationId: UUID; // the invitation id associated with the event
  }
}

// Event Name: widget_render
// Available via onEvent in Widget: true
// Event origins: This event is emitted your widget is rendered.
// Event Format:

type widgetRender extends BaseEvent {
  platform: 'web' | 'ios' | 'android';
  useragent?: string; // the viewing user's user agent
  referer?: string;
  refererDomain?: string;
  sessionId?: UUID; // the session id, generated by the widget for the session that created the invitation
  foreignUserId?: string; // this event is associated with the user who created the invitation in your system
  segmentation?: Record<string, any>; // segmentation of the event as specified by the widget prop at invitation creation time
  payload?: null;
}

// Event Name: email_invitations_submitted
// Available via onEvent in Widget: true
// Event origins: This event is emitted one of your users submits an invitation form.
// Event Format:

type emailInvitationsSubmitted extends BaseEvent {
  platform: 'web' | 'ios' | 'android';
  useragent?: string; // the viewing user's user agent
  referer?: string;
  refererDomain?: string;
  sessionId?: UUID; // the session id, generated by the widget for the session that created the invitation
  foreignUserId?: string; // this event is associated with the user who created the invitation in your system
  segmentation?: Record<string, any>; // segmentation of the event as specified by the widget prop at invitation creation time
  payload?: {
    formData: Record<string, any>; // this is the raw form data that is being sent to create invitations
  };
}

// Event Name: widget_email_field_focus
// Available via onEvent in Widget: true
// Event origins: This event is emitted one of your users puts focus on the email form field.
// Event Format:

type widgetEmailFieldFocus extends BaseEvent {
  platform: 'web' | 'ios' | 'android';
  useragent?: string; // the viewing user's user agent
  referer?: string;
  refererDomain?: string;
  sessionId?: UUID; // the session id, generated by the widget for the session that created the invitation
  foreignUserId?: string; // this event is associated with the user who created the invitation in your system
  segmentation?: Record<string, any>; // segmentation of the event as specified by the widget prop at invitation creation time
  payload?: {
    timestamp: number // the number of MS since the form was rendered
  };
}

// Event Name: widget_email_field_blur
// Available via onEvent in Widget: true
// Event origins: This event is emitted one of your users blurs the email form field that was once in focus.
// Event Format:

type widgetEmailFieldBlur extends BaseEvent {
  platform: 'web' | 'ios' | 'android';
  useragent?: string; // the viewing user's user agent
  referer?: string;
  refererDomain?: string;
  sessionId?: UUID; // the session id, generated by the widget for the session that created the invitation
  foreignUserId?: string; // this event is associated with the user who created the invitation in your system
  segmentation?: Record<string, any>; // segmentation of the event as specified by the widget prop at invitation creation time
  payload?: {
    timestamp: number // the number of MS since the form was rendered
  };
}

// Event Name: widget_email_validation
// Available via onEvent in Widget: true
// Event origins: This event is emitted when an email validation is done within the widget. It includes the results of your validation function if passed
// Event Format:

type widgetEmailValidation extends BaseEvent {
  platform: 'web' | 'ios' | 'android';
  useragent?: string; // the viewing user's user agent
  referer?: string;
  refererDomain?: string;
  sessionId?: UUID; // the session id, generated by the widget for the session that created the invitation
  foreignUserId?: string; // this event is associated with the user who created the invitation in your system
  segmentation?: Record<string, any>; // segmentation of the event as specified by the widget prop at invitation creation time
  payload?: {
    email: string;
    isValid: boolean;
  };
}

// Event Name: widget_share_link_click
// Available via onEvent in Widget: true
// Event origins: This event is emitted when your user clicks on any sharing destination in your widget
// Event Format:

type widgetShareLinkClick extends BaseEvent {
  platform: 'web' | 'ios' | 'android';
  useragent?: string; // the viewing user's user agent
  referer?: string;
  refererDomain?: string;
  sessionId?: UUID; // the session id, generated by the widget for the session that created the invitation
  foreignUserId?: string; // this event is associated with the user who created the invitation in your system
  segmentation?: Record<string, any>; // segmentation of the event as specified by the widget prop at invitation creation time
  payload?: {
    clickName: string; // the text of the copy share link element
  };
}

// Event Name: widget_email_validation_error
// Available via onEvent in Widget: true
// Event origins: This event is emitted when your user attempts to submit an invitation form and the input results in an error.
// Event Format:

type widgetSubmitValidationError extends BaseEvent {
  platform: 'web' | 'ios' | 'android';
  useragent?: string; // the viewing user's user agent
  referer?: string;
  refererDomain?: string;
  sessionId?: UUID; // the session id, generated by the widget for the session that created the invitation
  foreignUserId?: string; // this event is associated with the user who created the invitation in your system
  segmentation?: Record<string, any>; // segmentation of the event as specified by the widget prop at invitation creation time
  payload?: {
    formData: Record<string, any>; // the data of the form that produced the error
  };
}

// Event Name: widget_email_submit_error
// Available via onEvent in Widget: true
// Event origins: This event is emitted when your user attempts to submit an invitation form the configuration results in an error.
// Event Format:

type widgetEmailSubmitError extends BaseEvent {
  platform: 'web' | 'ios' | 'android';
  useragent?: string; // the viewing user's user agent
  referer?: string;
  refererDomain?: string;
  sessionId?: UUID; // the session id, generated by the widget for the session that created the invitation
  foreignUserId?: string; // this event is associated with the user who created the invitation in your system
  segmentation?: Record<string, any>; // segmentation of the event as specified by the widget prop at invitation creation time
  payload?: {
    error: string; // the error message
  };
}

// Event Name: widget_error
// Available via onEvent in Widget: true
// Event origins: This event is emitted when your user attempts to render your widget and it has an error.
// Event Format:

type widgetError extends BaseEvent {
  platform: 'web' | 'ios' | 'android';
  useragent?: string; // the viewing user's user agent
  referer?: string;
  refererDomain?: string;
  sessionId?: UUID; // the session id, generated by the widget for the session that created the invitation
  foreignUserId?: string; // this event is associated with the user who created the invitation in your system
  segmentation?: Record<string, any>; // segmentation of the event as specified by the widget prop at invitation creation time
  payload?: {
    error: string; // the error message
  };
}

// Event Name: unfurl
// Available via onEvent in Widget: false
// Event origins: This event is emitted when we detect that the shareable link has been shared. Vortex detects the automated request from various systems and responds with rich content for your shareable links so that when users of these 3rd parties view the link, it is decorated with more enticing content to encourage a click through.
// Event Format:

type unfurl extends BaseEvent {
  platform: 'share';
  useragent?: string; // the viewing user's user agent
  referer?: string;
  refererDomain?: string;
  sessionId?: UUID; // the session id, generated by the widget for the session that created the invitation
  foreignUserId?: 'anon-email'; // this event is associated with the user who created the invitation in your system
  segmentation?: Record<string, any>; // segmentation of the event as specified by the widget prop at invitation creation time
  payload?: {
    invitationId: UUID; // the id of the shareable link
  };
}