Challenges#

The Antavo challenge module provides a simple user-friendly interface for counting and incentivizing customer behavior by monitoring submitted events. The typical uses of the Challenge module include:

  • Counting the number of customer interactions with the loyalty platform

    • Any event type can be used, including custom events.

      • e.g., daily_login, checkout, point_add

    • Qualifying interactions can also be restricted by any property recorded on the counted event.

      • e.g., a checkout event total has to be greater than 100 or the quantity field has to equal 10 items

    • Interactions can also have complex time requirements.

      • e.g., Do this activity X times in a day/week/month

      • e.g., Do this activity X times every X days for X months

    • Gamification.

      • Challenges can be one-time only or have numerous possible repeat permutations.

      • Points can be directly awarded upon successful completion

  • Generating a total for a fixed number of specifics events.

    • A running total is calculated and maintained from a specific attribute from qualifying events.

    • A challenge is completed when a target threshold is reached.

    • The maximum and minimum number of contributing events can be defined.

      • e.g., a customer spends more than 1000 GBP within 5 transactions in a checkout

  • A complex trigger

    • A completed challenge results in an event being written to the customer’s event stream.

    • This event trigger can be used in workflows.

  • Badges

    • A visual Progress/target tracking of a customer’s current performance by combining performance statistics with graphics.

    • Overall and individual sub-challenge progress is accessible.

    • The number of times that a particular challenge has been completed is also available.

      • Successfully completed challenge information is available via API even when the challenge is not longer active.

      • Challenges can also be directly awarded from workflow editor counting as a challenge completion.

Challenges must be configured in the back office and this process is described in the user manual.

API monitoring#

The challenge module monitors the customer event stream and as such, it is only possible to directly influence challenges by submitting events via the events API. However, it is possible to monitor customers’ progress via two API calls. Available challenges lists all active available challenges and their current status for the customer whilst completed challenges lists all completed challenges, independently of the current status of the challenge.

Available challenges#

The /customers/{customer_id}/activities/challenges endpoint returns the status for the current customer for all active available challenges.

The progress array in the response contains the current status of the challenge where:

  • overall is the total progress of the challenge, reported as a percentage. This value is generated from the threshold/current values from all criteria.

  • criteria is an array of objects containing

    • action - the triggering event action

    • message - A string field containing information regarding the criteria to be displayed to the customer

    • threshold - The number of valid actions required for completion

    • current- The current number of valid actions counted in the current challenge

    • is_completed - A Boolean showing the status of the criteria

The completion field shows the number of times the challenge has been successfully finished; the image field can be used to store a graphical badge and points returns the number of automatically assigned loyalty points, upon challenge completion.

{
  "data": [
    {
      "id": "5c17c37f71f86e7f798b4576",
      "title": "Test challenge",
      "description": "This is the long description of the challenge",
      "status": "active",
      "image": {
        "small": "https://example.com/image0001_small.jpg",
        "medium": "https://example.com/image0001_medium.jpg",
        "large": "https://example.com/image0001_large.jpg"
      },
      "points": 120,
      "message": "string",
      "cta_label": "string",
      "url": "https://example.com/challenge",
      "ends_at": "2022-08-29T13:08:28.393Z",
      "completions": 3,
      "progress": {
        "overall": 67,
        "criteria": [
          {
            "action": "checkout",
            "message": "Make at least 5 purchases",
            "threshold": 5,
            "current": 2,
            "is_completed": false
          }
        ]
      },
      "tags": [
        "featured",
        "new"
      ]
    }
  ]
}

Completed challenges#

/customers/{customer_id}/challenges consists of a simple list of completed challenge objects. Each challenge object contains:

  • The unique ID of the challenge.

  • The title of the challenge.

  • The Created at date.

  • Last completed date.

  • The number of completions.