Garmin

The Garmin integration facilitates tracking customers' sports activities and incentivizes their engagement through loyalty benefits.

The integration generates events based on the activities logged in customers’ personal Garmin accounts. These activities can be recorded using Garmin activity trackers like watches, or uploaded manually through the Garmin Connect mobile app or website.

Prerequisites

Before you start configuring the Garmin integration, ensure you’ve completed the following steps:

• Create a Garmin developer account

• Log in to the Garmin Developer Portal

• Make sure the Garmin integration is enabled in the Management UI

  • Navigate to the Modules menu

  • Use the search bar to find the Garmin integration

  • If the Configure button is not accessible, please reach out to the Antavo Service Desk to enable the integration for you

Creating a Garmin app

To track customers' Garmin activities within Antavo, you must have a Garmin app for production purposes.

• Log in to the Garmin Developer Portal

• Navigate to the Apps tab to view the list of existing apps

• Click the Add App button to create a new app

  

• Provide the OAuth redirect URL
  Enter https://api.{environment}.antavo.com/garmin/oauth, where {environment} corresponds to the Antavo setup environment. This URL serves as the endpoint through which Garmin informs Antavo about the success or failure of the customer’s connection attempt.

• Select the Product purpose
  If this is your first app creation, please create an app for Evaluation purposes first. Subsequently, proceed with configuring the product purpose app, which will be used to monitor the activities of loyalty program members.

Connecting Garmin in Antavo

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

Setting up the Garmin Integration module

• Navigate to the Modules menu

• Find the Garmin integration and click Configure

  

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

  

• Enter the Garmin OAuth Redirect URL, which 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 Management UI, 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 Management UI, under the Garmin Deregistrations URL field.

  • Ensure that the enabled checkbox is active

Customers must be provided with a connection link to grant 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:

https://api.{environment}.antavo.com/v1/garmin/oauth/{customer_id}/{public_api_key}

Where:

• {environment} is the API environment currently in use, which should align with the setup environment,

• {customer_id} is the unique identifier assigned to each customer,

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

When customers click this link, they will be prompted to agree to the Garmin App Privacy Policy before consenting 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: indicates that the connection was successful
  This ensures that Antavo receives the customer’s Garmin ID, providing information about the owner of the activity.

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

Setting up the Garmin integration service

To ensure all requests are processed successfully, Garmin API calls are not immediately processed. Instead, they are queued for later processing.

To activate the service managing the queue, set up a new cron job.

When configuring the new cron job, ensure:

• 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 best performance

Request queue

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

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.

• 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 Add a criterium, then select Garmin activity from the drop-down list

• Click 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 should ride a bicycle on the road for 3 hours to receive a coupon.

• Set up a new workflow

• Drag and drop an Event trigger to the canvas

• As Event 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 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