Pre-release — content may change.

GuidesIntegrating with Wicket

Creating Touchpoints

How to track user activities and events using touchpoints

Touchpoints record user activities and events from integrated platforms, providing a comprehensive view of member engagement across your ecosystem.

Overview

A touchpoint tracks a meaningful interaction a person has within an association's integrated ecosystem. An association's integrated ecosystem in this case refers to any system connected to Wicket and set up to create touchpoints within Wicket.

A touchpoint captures a specific interaction or event:

  • What happened: The action taken (e.g., "Event Attended")
  • Who did it: The person involved
  • When it occurred: Timestamp of the activity
  • Context: Additional details about the event

Touchpoint Structure

Each touchpoint contains:

FieldDescriptionExample
person_idWicket person UUID"abc123-..."
service_idIntegration service UUID"def456-..."
actionHuman-readable description"Order Completed"
codeMachine-readable identifier"order_completed"
detailsAdditional context"Product: Pro Plan\\n\\nOrder Total: $99.00 USD"
dataAdditional context (JSON){"product_name": "..."}
external_event_idUnique identifier for the activity"your_platform:unique_event_id"
created_atWhen the event happened"2025-01-15T10:30:00Z"

Creating a Touchpoint

POST /touchpoints

{
  "person_id": "wicket-person-uuid",
  "service_id": "your-service-uuid",
  "action": "Order Completed",
  "code": "order_completed",
  "details": "Product: Pro Plan\\n\\nOrder Total: $99.00 USD",
  "external_event_id": "your_platform:unique_event_id",
  "data": {
    "order_id": 12345,
    "order_total": 99.00,
    "currency": "USD",
    "product": "Pro Plan"
  },
  "created_at": "2025-01-01T06:00:00.000Z"
}

How touchpoints are built

Action (Human-Readable)

  • Use past tense: "Attended event", "Purchased product"
  • Be descriptive but concise
  • Consistent capitalization

Code (Machine-Readable)

  • Use snake_case: event_attended, product_purchased
  • Be specific and consistent

Details vs Data

The details and data fields serve different purposes but should be built together:

  • details (string): Human-readable text displayed in the UI. Build it dynamically to show only relevant information.
  • data (JSON): Structured data for programmatic access. Maintain a consistent structure across all touchpoints of the same type.

Best practices:

  1. Include all displayable information from details in data as well, so it's not necessary to extract values from the details string.
  2. Include IDs and other metadata in data that may be useful for future development or integrations, even if not displayed in details.
  3. For optional fields, conditionally include them in details only when they have values (to keep a clean UI), but always include them in data with null to maintain a consistent structure.

Example with optional event price:

{
  "details": "Event: Annual Conference 2025\n\nDate: January 15, 2025\n\nPrice: $99.00",
  "data": {
    "event_id": "evt_123",
    "event_name": "Annual Conference 2025",
    "event_date": "2025-01-15",
    "event_price": 99.00
  }
}

When there's no price:

{
  "details": "Event: Annual Conference 2025\n\nDate: January 15, 2025",
  "data": {
    "event_id": "evt_123",
    "event_name": "Annual Conference 2025",
    "event_date": "2025-01-15",
    "event_price": null
  }
}

Common Touchpoint Patterns

E-commerce

ActionCode
Order Createdorder_created
Order Processingorder_processing
Order Pendingorder_pending
Order On-Holdorder_on_hold
Order Marked Completedorder_marked_completed
Order Refundedorder_refunded
Order Cancelledorder_cancelled
Order Deletedorder_deleted

Event Management

ActionCode
Registered for an eventevent_registered
Attended an eventevent_attended

Learning Management System

ActionCode
Enrolled in a courseenrolled_in_a_course
Completed a coursecompleted_a_course

Email Marketing

ActionCode
Email Clickedemail_clicked
Email Openedemail_opened
Email Subscribedemail_subscribed
Email Unsubscribedemail_unsubscribed

Accreditation Software

ActionCode
Submission Startedsubmission_started
Submission Completesubmission_complete

Timing Considerations

Use created_at to specify when the actual event happened. Always use the external platform's event timestamp for created_at to maintain accurate timelines.

Historical Data

When importing historical data:

  1. Set created_at to the original event time
  2. Process in chronological order when possible

Deduplication

Prevent duplicate touchpoints by using the external_event_id field. This field acts as an idempotency key - if a touchpoint with the same external_event_id already exists, a new one will not be created.

Bulk Touchpoint Creation

For importing multiple touchpoints:

POST /touchpoints/bulk
{
  "touchpoints": [
    {
      "person_id": "...",
      "service_id": "...",
      "action": "...",
      "code": "...",
      "created_at": "..."
    },
    // ... more touchpoints
  ]
}

Best Practices

  1. Be consistent: Use the same action/code patterns across your integration
  2. Include context: Add relevant details and data for future analysis
  3. Use accurate timestamps: Always use the event's actual time
  4. Avoid duplicates: Check before creating, especially for webhooks
  5. Document codes: Maintain a reference of all touchpoint codes you create
  6. Keep details structured: Use consistent field names in details JSON

On this page