[Gametize Tech] API: Challenge Time Tracking (With Min. View Duration Support)

Design

Similar to project time tracking, users' time in challenge is being tracked between 2 actions. However, the mechanism is fundamentally different from project time tracking due to the following constraints:

• It is difficult to monitor entering and exiting challenge (For project, this is simple, as any data or action via API can be correlated to project and therefore knowing if user has entered or exited project).

• The viewing duration data in challenge will be utilised for minimum view duration function in challenge. Therefore, it is detrimental to record every viewing session as a row (like project), where potentially the table will grow to a large size and affects performance.
  
  

To mitigate the above, challenge time tracking adopts the following changes:

• 1 row of data per user per challenge (Cons: data has to be well protected as the single row represents the entire challenge duration record of a user’s interaction with one challenge)

• Introduction of exit API (Cons: require implementation on the applications)
  
  

Challenge time tracking data is being stored in the table challenge_log.

And for analytics purpose, the most important information is totalDuration (Can be used as-is to represent total user time in viewing a specific challenge)

Threshold and Buffer

Due to the nature of API call, it is not easy to reliably track viewing duration. One of the most common issues is user exiting the app without calling any actions to end time tracking. To mitigate this issue, the same mechanism as project time tracking is employed: threshold and buffer.

For refresher and illustration, please refer to the following sequence:

1. Threshold is set at 300 seconds*

2. Buffer is set at 90 seconds*

Normal usage:

• User triggers enter challenge at time 0 seconds

• User triggers exit challenge at time 20 seconds

• System checks if duration is greater than threshold and finds it is within threshold

• System records 20 seconds of viewing time for the challenge

Threshold and buffer usage:

• User triggers enter challenge at time 0 seconds

• User exits application - No exit challenge is triggered

• User comes back to application and triggers exit challenge at time 10000 seconds (If recorded as is, the data will skew analytics significantly)

• System checks if duration is greater than threshold and finds it has crossed the threshold

• System records the pre-determined buffer of 90 seconds of viewing time for the challenge

Special events:

• If user triggers enter challenge multiple-times, no action will be taken if duration since start is within threshold

• If user triggers enter challenge multiple-times, buffer will be recorded and session will restart if threshold has been crossed

Implementation of Challenge Time Tracking

Enter and exit challenge may be triggered by the following APIs.

Enter Challenge:

• Start (Enter) challenge viewing (NEW API) - api2/challenges/ID/start_view.json

Exit Challenge:

• End (Exit) challenge viewing (NEW API) - api2/challenges/ID/end_view.json

IMPORTANT - Implementation notes based on Gametize app designs:

• Time start trigger is not incorporated into show challenge profile API as it may be used beyond viewing challenge. Therefore, start challenge trigger needs to be incorporated into our current apps.

• Furthermore, exit challenge trigger needs to be incorporated into our current apps since relying on Complete challenge action is unreliable (User may often exit challenge without completing it). The possible implementation points:

  • Trigger exit challenge if “Back” is toggled

  • Trigger exit challenge if next page is loaded (i.e. user navigates to a user profile page from challenge profile)

  • Trigger exit challenge if app is exited (Used to be possible on iOS SDK)

Implementation of Min. View Duration

IMPORTANT - This feature is designed based on the following conditions:

• Challenge time tracking is enabled

• Challenge must not be an information card

• Challenge must be completed by players (Administrator will skip the viewing requirement if set)

• If threshold and buffer are set, min. view duration will override either/both threshold and buffer if its value is greater

Guidelines:

• Display min. view duration to user

  • If set, data is returned via /api2/challenges/ID.json

  • Utilise challengeMinViewDuration (int in seconds) and/or challengeMinViewDurationFormatted (String)

  • IMPORTANT - Consider implementing button lock with time control (i.e. Unlock button once min. view duration is satisfied)

• Before completing a challenge with min. view duration, please ensure that the following API has been triggered to start the timer:

  • Start (Enter) challenge viewing (NEW API) - api2/challenges/ID/start_view.json

Outcomes:

1. Complete challenge is triggered before starting the view session:
   
   

   Open Screenshot 2023-05-15 at 5.42.39 PM.png

   

   Resolution: Trigger Show challenge profile API or Start challenge viewing API.
   
   

2. Complete challenge is triggered before satisfying the min. view duration requirement:
   
   

   Open Screenshot 2023-05-15 at 5.43.45 PM.png

   

Note:

The article's technical specifications and details are subject to potential changes based on our discretion. It is important to note that the information presented in the article might have become outdated or lost its relevance in the present context.

If you are interested to learn more about this, please drop an email to support@gametize.com with your queries regarding the article!