Garmin

The Garmin integration allows to track customers' sport activities and incentivizes their engagement through loyalty benefits.

The integration creates events based on the customers' activities logged in their personal Garmin account. These activities can be recorded using Garmin activity trackers, such as watches, or uploaded manually through the Garmin Connect mobile app or website.

Prerequisites

Before you start configuring the Garmin integration, make sure you've done the following:

• Create a Garmin developer account

• Log in to the Garmin Developer Portal

• Make sure the Garmin integration is enabled in the Backoffice

  • Go to the Modules menu by clicking the icon

  • Use the search bar to find the Garmin integration

  • If the ‘Configure' button is not available, please contact the Antavo Service Desk to enable the integration for you

Creating a Garmin app

To track customers' Garmin activities within Antavo, you need to have a Garmin app for production purpose.

• Log in to the Garmin Developer Portal

• Click the 'Apps' tab to access the list of existing apps

• Click the 'Add App' button to create a new app

Open

• Provide the OAuth redirect URL
  Enter https://api.{environment}.antavo.com/garmin/oauth, where {environment} corresponds to the Antavo setup environment. This is the URL through which Garmin notifies Antavo that the customer’s connection attempt was successful or not.

• Select the Product purpose
  If this is the first app that you create, please create an app for Evaluation purpose before you start setting up the product purpose app that you will use to track loyalty program members' activities.

Connecting Garmin in Antavo

To link the Garmin app with Antavo, you first need to configure the Garmin integration in Antavo’s Backoffice, and then configure the Garmin app to send data to Antavo.

Setting up the Garmin Integration module

• Go to the Modules menu by clicking on the icon

• Find the Garmin integration and click 'Configure'

Open

• Insert the Consumer Key and Consumer Secret of the newly created Garmin app

• Enter the Garmin OAuth Redirect URL
  This is the desired URL where customers will be redirected after completing the connection process.

• Click ‘Save’

Enable Garmin to send activity data to Antavo

• Open the Garmin Developer Portal and navigate to the ‘API Tools’ section

• Enter the Consumer Key and Consumer Secret of the Garmin app

• Fill in the 'ACTIVITY - Activity Details’ item

  • Paste the Garmin Activity Callback URL
    You can find it on the Garmin Connection Settings page in Antavo’s Backoffice, under the 'Garmin Activity Callback URL' field.

  • Ensure that the ‘enabled’ checkbox is active

  • From the drop-down menu, select push

• Fill in the 'COMMON - Deregistrations' item

  • Paste the Garmin Deregistrations URL
    You can find it on the Garmin Connection Settings page in Antavo’s Backoffice, under the 'Garmin Deregistrations URL' field.

  • Ensure that the ‘enabled’ checkbox is active

Creating a connect url

Customers need to be provided with a connection link, which is necessary because they need to give their consent to the app to access their activity data. This data is then used in the loyalty program mechanism.

The link should be created in the following format:

Where:

• {environment} is the API environment in use (should match the setup environment)

• {customer_id} is the unique identifier of the customer

• {public_api_key} is the API key assigned to the program

Customers who click this link will be prompted to agree to the Garmin App Privacy Policy to share their data.

When customers click the ‘Agree’ button, the system redirects them to the previously configured redirect URL within the module settings.

The redirect URL is extended with a parameter that identifies whether the connection was successful or not. Based on the parameter, you can configure communication about the result of the connection to the customer on the website. The possible outcomes are:

• ?status=success: the connection was successful
  This ensures that Antavo receives the customer’s Garmin ID, providing information about the owner of the activity.

• ?status=error: the connection was unsuccessful because the customer denied access, or any other issue occurred.

Setting up the Garmin integration service

To ensure that the program can process every request successfully, the Garmin API calls are not automatically processed. Instead, they are added to a queue for later processing.

To enable the service that processes the queue, you need to set up a new cron job.

When you set up the new cron job, ensure the following:

• The ‘Task’ field must be garmin-queue-processor

• The ‘Action’ field must be process

• No parameters are needed or supported

• It is recommended to run the job every minute or every 5 minutes for optimal performance

Request queue

Here you can find the queue of activities coming from customers' Garmin accounts.

• Identifier - The unique ID of the activity

• Created At - Timestamp indicating when the activity was added to the queue

• Started At - Timestamp indicating when the processing of the activity started

• Finished at - Timestamp indicating when the processing of the activity was completed

• Request URI - The URI where the request was sent to

• Request Method - The method used for requesting the activity (e.g., GET, POST)

• Status - The status of the activity processing (e.g., pending, finished)

• Type - The type of the activity request

• Customer - The customer associated with the activity

When the request is successfully processed, the Garmin activity is registered in the customer’s event history.

Use cases

To reward customers with loyalty benefits, you'll need to set up Workflows and/or Challenges where Garmin activities will serve as triggers for other actions, such as rewarding customers with loyalty points or assigning them coupons.

Use case - Walk for an hour over the weekend and earn 100 loyalty points

In this challenge, customers need to walk for an hour over the weekend to earn 100 loyalty points.

Here's how to set up a challenge like this:

• Create a new Challenge.

• In the ‘Points’ field, enter ‘100’

• Set the Start date and End date according to your needs

• In the ‘Criteria’ field, click on ‘Add a criterium’, then select ‘Garmin activity’ from the drop-down list

• Click on ‘Add filter’, then

  • Select ‘activity_type’ as an Attribute

  • Select ‘equals to’ as an Operator

  • Enter ‘CASUAL_WALKING’ as a Value. At the bottom of the article, you can find the full list of Garmin activities.

• Click on ‘Add filter’ again, then

  • Select ‘duration_in_seconds’ as an Attribute

  • Select ‘is greater than or equal to’ as an Operator

  • Enter '3600' as a Value

• Set ‘1 times’ as a Criterium

• Make sure you activate the challenge

Use case - Ride for 3 hours and receive a coupon

In this challenge, customers need to ride a bicycle on the road for 3 hours to receive a coupon. Here's how to set up a challenge like this:

• Set up a new Workflow.

• Drag and drop an Event trigger to the canvas

• As Event’s type, select ‘Garmin activity’

• Connect an Event attribute filter to the action branch of the Event trigger, then

  • Select ‘Activity type’ as an Attribute

  • Select ‘equals to’ as an Operator

  • Enter ‘ROAD_CYCLING’ as a Value. At the bottom of the article, you can find the full list of Garmin activities.

  • Click on the ‘And’ button

  • Select ‘Duration in seconds’ as an Attribute

  • Select 'is greater than or equal to’ as an Operator

  • Enter ‘10800’ as a Value

• Connect an Assign coupon action node to the success branch of the Event attribute filter

• Double click on Assign coupon and fill in the fields as per your needs

Full list of Garmin activity types

When configuring a Challenge or Workflow, you may need to include Garmin activities as conditions for specific scenarios. Here, you can access the comprehensive list of Garmin activity types:

“RUNNING” Category

INDOOR_RUNNING
OBSTACLE_COURSE_RACING
STREET_RUNNING
TRACK_RUNNING
TRAIL_RUNNING
TREADMILL_RUNNING
ULTRA_RUNNING
VIRTUAL_RUNNING
HIKING

“CYCLING” Category

BMX
CYCLOCROSS
DOWNHILL_BIKING
EBIKING
EMOUNTAINBIKING
GRAVEL_UNPAVED_CYCLING
INDOOR_CYCLING
MOUNTAIN_BIKING
RECUMBENT_CYCLING
ROAD_CYCLING
TRACK_CYCLING
VIRTUAL_CYCLING
HANDCYCLING
INDOOR_HANDCYCLING

“GYM & FITNESS EQUIPMENT” Category

BOULDERING
ELLIPTICAL
CARDIO
HIIT
INDOOR_CLIMBING
INDOOR_ROWING
PILATES
STAIR_STEPPER
STRENGTH_TRAINING
YOGA
MEDITATION
“SWIMMING” Category

POOL_SWIMMING
OPEN_WATER_SWIMMING

“WALKING/INDOOR WALKING” Category

CASUAL_WALKING
SPEED_WALKING

“WINTER SPORTS” Category

BACKCOUNTRY_SNOWBOARDING
BACKCOUNTRY_SKIING
CROSS_COUNTRY_CLASSIC_SKIING
RESORT_SKIING
SNOWBOARDING
RESORT_SKIING_SNOWBOARDING
CROSS_COUNTRY_SKATE_SKIING
SKATING
SNOWSHOEING
SNOWMOBILING

“WATER SPORTS” Category

BOATING
FISHING
KAYAKING
KITEBOARDING
OFFSHORE_GRINDING
ONSHORE_GRINDING
PADDLING
ROWING
SAILING
SNORKELING
STAND_UP_PADDLEBOARDING
SURFING
WAKEBOARDING
WATERSKIING
WHITEWATER
WINDSURFING

“TRANSITION” Category

BIKE_TO_RUN_TRANSITION
RUN_TO_BIKE_TRANSITION
SWIM_TO_BIKE_TRANSITION

“TEAM SPORTS” Category

AMERICAN_FOOTBALL
BASEBALL
BASKETBALL
CRICKET
FIELD_HOCKEY
ICE_HOCKEY
LACROSSE
RUGBY
SOCCER_FOOTBALL
SOFTBALL
ULTIMATE_DISC
VOLLEYBALL

“RACKET SPORTS” Category

BADMINTON
PADEL
PICKLEBALL
PLATFORM_TENNIS
RACQUETBALL
SQUASH
TABLE_TENNIS
TENNIS

“OTHER” Category

BOXING
BREATHWORK
DANCE
DISC_GOLF
FLOOR_CLIMBING
GOLF
INLINE_SKATING
MIXED_MARTIAL_ARTS
MOUNTAINEERING
ROCK_CLIMBING
STOPWATCH

“PARA SPORTS” Category

WHEELCHAIR_PUSH_RUN
WHEELCHAIR_PUSH_WALK