Derive Engagement with Challenge UI Elements

As businesses look for new ways to engage with their customers, loyalty programs have become an increasingly popular tool for incentivizing customer behavior and building strong relationships. And when it comes to loyalty programs, few platforms are as robust and effective as Gameball.

With Gameball, businesses can easily create customized challenges and rewards that encourage customers to engage with their brand and make repeated purchases. And by integrating Gameball into your platform, you can create a seamless loyalty experience that keeps customers coming back for more.

In this article, we'll explore a scenario where you want to motivate your customers to complete their profile details on your platform. We will create a challenge that is linked to an event which you will send once the customer completes his profile. Once gameball receives this event, the customer will be rewarded the challenge automatically.

1. Setting Up the Challenge

We will start by creating the event on Gameball. log in to the Gameball dashboard and set up an event to be sent when a player completes their profile. This event will be used to trigger the rewarding of points or coupons based on your challenge configuration. You can visit this link to add the event, let's assume the event was named profile_completed.

You will need to configure your backend to send the profile_completed event when a player completes his profile on your platform. You can check this tutorial for more details on how to send and track your customers actions on your platform.

After creating the event, you can create a new challenge called "Complete Your Profile.". Please follow this tutorial on how to create a custom-event challenge.

Sample challenge trigger configuration

After this configuration, if you send profile_completed through the API, the player will be rewarded with the Profile Completed challenge.

2. Using the Player Progress API

With the challenge and event set up, you can now use the Player Progress API to track whether a player has completed their profile. The Player Progress API allows the client to query a player's progress towards a particular challenge or set of challenges, giving them real-time insights into the player's behavior and motivations.

If the Player Progress API indicates that the player has not yet completed the "Complete Your Profile" challenge, the client can use this information to motivate the player to finish the challenge. For example, they might display a pop-up message or banner on their application that encourages the player to complete their profile in exchange for points or rewards.

By using the Player Progress API in this way, the client can create a more personalized and engaging loyalty experience for their players. And by incentivizing behavior that aligns with their business goals, they can drive increased customer engagement and loyalty over time.

To get the challenge progress for a specific player, you’ll need to send a GET request to the Gameball API progress endpoint. The endpoint url is:

https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}/progress/challenge/{handle}

Make sure to provide both of the API key and Secret key in the request header

You will replace the {playerUniqueId} parameter with the current logged in player’s unique id, and the {handle} can be replaced with the challenge id, you can find it right here:

The API response would contain A single object array of ChallengesProgress object. Where the challenge progress contains many useful information as achievedCount attribute which states the number of times the player was rewarded the challenge.

{
    "challengesProgress": [
        {
            "completionPercentage": 0.0,
            "achievedCount": 1,
            "challengeConfig": {
                "id": 5196,
                "name": "Complete your profile",
                "description": "Unlock this challenge by completing all of your profile information",
                "isRepeatable": false,
                "maxAchievement": 1,
                "type": "EventBased",
                "visibility": "Always Visible",
                "rewards": [
                    {
                        "rankReward": 0,
                        "walletReward": 5,
                        "couponReward": null
                    }
                ]
            }
        }
    ]
}

In your own UI, you can trigger a popup for example if you detect that for this specific challenge, the current player has achievedCount of 0, This means that this player didn’t achieve this challenge yet, so you can motivate them to achieve this challenge to earn its rewards. The rewards object will contain the details of the challenge reward. Refer to the API Reference for more information.

3. Showing all challenges progress on your platform

Using the progress API, you can display challenges to players directly on your platform. You can show them to motivate players and show them all the challenges they have already achieved and also what they can achieve.

you’ll need to send a GET request to the Gameball API progress endpoint. The endpoint url is:

https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}/progress

The response will result in a summarized view of the player’s progress over various gameball programs as levels and points. For the scope of this tutorial we will only focus on challengesProgress object.

{
    "challengesProgress": [
        {
            "completionPercentage": 0.0,
            "achievedCount": 1,
            "challengeConfig": {
                "id": 1234,
                "name": "Bags lover",
                "description": "Place an order with an item of the bags collection in your cart",
                "rewards": [
                    {
                        "rankReward": 0,
                        "walletReward": 100,
                        "couponReward": null
                    }
                ],
                "isRepeatable": false,
                "maxAchievement": 1,
                "icon": "https://cdn.gameball.co/uploads/gb-library/general/shopping-10.png"
            }
        },
        {
            "completionPercentage": 0.0,
            "achievedCount": 2,
            "challengeConfig": {
                "id": 1235,
                "name": "The shopper",
                "description": "Place an order and win the badge!",
                "rewards": [
                    {
                        "rankReward": 0,
                        "walletReward": 50,
                        "couponReward": null
                    }
                ],
                "isRepeatable": true,
                "maxAchievement": -1,
                "icon": "https://cdn.gameball.co/uploads/gb-library/general/cashback.png"
            }
        },
        {
            "completionPercentage": 66.0,
            "achievedCount": 0,
            "challengeConfig": {
                "id": 1236,
                "name": "HaTrick!",
                "description": "Place 3 orders to earn this badge!",
                "rewards": [
                    {
                        "rankReward": 0,
                        "walletReward": 300,
                        "couponReward": null
                    }
                ],
                "isRepeatable": false,
                "maxAchievement": 1,
                "icon": "https://cdn.gameball.co/uploads/gb-library/general/shopping-8.png"
            }
        }
    ]
}

The challengesResponse will be an array of all of your challenges, and a summary of the player’s progress on each challenge.

Attribute	Description
completionPercentage	A value between 0 and 1 indicating the current player’s progress in the challenge if it requires multiple actions to be achieved.
achievedCount	The number of times the player has earned the challenge
challengeConfig	Extra details about the challenge configurations. You can find further documentation here.

Here is an example using HTML and CSS on how to use the progress API to render your challenges on your own platform:

<!DOCTYPE html>
<html>


<head>
    <meta charset="utf-8">
    <title>Gameball Challenges</title>
    <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
    <style>
        .challenge {
            display: inline-block;
            margin-right: 25px;
            margin-top: 15px;
            text-align: center;
        }


        .challenge-icon {
            border-radius: 50%;
            width: 50px;
            height: 50px;
            background-color: #f2f2f2;
        }


        .challenge-text {
            font-size: 12px;
            margin-top: 5px;
        }


        .challenge-count {
            font-size: 14px;
            font-weight: bold;
            margin-top: 5px;
        }
    </style>
</head>


<body>
    <h1>Gameball Challenges</h1>
    <div id="challenges"></div>


    <script>
        $(document).ready(function () {
            var playerUniqueId = "player1234"; // Replace with the player unique Id
            var apiKey = "<api-key>"; // Replace with your actual API key


            $.ajax({
                url: "https://api.gameball.co/api/v3.0/integrations/player/" + playerUniqueId + "/progress",
                type: "GET",
                dataType: "json",
                headers: {
                    "APIkEY": apiKey
                },
                success: function (response) {
                    if (response.challengesProgress && response.challengesProgress.length > 0) {
                        var challengesHtml = "";


                        $.each(response.challengesProgress, function (index, challenge) {
                            console.log(challenge);
                            var iconUrl = challenge.challengeConfig.icon


                            challengesHtml += '<div class="challenge">';
                            challengesHtml += `<img class="challenge-icon" src="${iconUrl}"></img>`;
                            challengesHtml += '<div class="challenge-text">' + challenge.challengeConfig.name + '</div>';
                            challengesHtml += '<div class="challenge-count">' + challenge.achievedCount + '</div>';
                            challengesHtml += '</div>';
                        });


                        $("#challenges").html(challengesHtml);
                    } else {
                        $("#challenges").html("No challenges found.");
                    }
                },
                error: function (xhr, status, error) {
                    console.log(xhr.responseText);
                }
            });
        });
    </script>
</body>


</html>