What are Quests?

Quests are sets of tasks that the user must be completed to achieve a quest goal. Quest tasks are individual tasks or jobs a user must complete in order to make progress on the quest. Quest tasks can be completed in any order to still have progress towards the Quest goal.

Why use Quests?

Quests give the end user a more gamified experience. They have to do multiple things in order to accomplish a single goal. During the quests, the user and integrators are able to see the progress of the quest. This progress allows the user to see how much is left in order for them to complete the quest.

Quests can be used to build things like:

  • New user on-boarding checklists
  • Product and feature tours
  • One-time promotional campaigns

Configuring Quests

From the CMS:

  1. Head to your Application on the Producer Site
  2. Select "Quests" in the Sidebar
  3. Select the "New Quest" button
  4. Set the Quest name, Description, and add at least one subtask.
  5. Select "Create" to finish
33363336

The quest is now created and should be visible in the Quest list view.

Getting Quest List

You can fetch a list of Quests available in current application. This list can be filtered by Quest IDs if you want to fetch only a few particular quests.

let sdk: EngagementSDK
let questRequest = GetQuestsRequestOptions()

sdk.quests.getQuests(
  page: .first,
  options: questRequest
) { result in
   
   switch result {
   case .failure(let error):
    // handle error             
   case .success(let quests):
    // handle success        
   }
}
LiveLike.getQuests({ questIds: ["123", "xyz"] })
  .then(padinatedResponse => console.log(padinatedResponse.results))
quests = (application as LiveLikeApplication).sdk.quests()

quests.getQuests(
    GetQuestsRequestOptions(),
    LiveLikePagination.FIRST,
    object : LiveLikeCallback<LLPaginatedResult<Quest>>() {
        override fun onResponse(result: LLPaginatedResult<Quest>?, error: String?) {
            error?.let {
                ...
            }

            result?.let {
                ...
            }
        }})

Starting a UserQuest

A UserQuest is an instance of a Quest that is attached to a user. Upon creating a UserQuest, UserQuestTasks will automatically be created, which will then be used to track progress, status, etc.

let sdk: EngagementSDK

sdk.quests.startUserQuest(
  questID: self.quest.id
) { result in
   
   switch result {
   case .failure(let error):
    // handle error             
   case .success(let userQuest):
    // handle success        
   }
}
LiveLike.startUserQuest({ questId: "xxxxx" })
  .then(userQuest => console.log(userQuest))
quests = (application as LiveLikeApplication).sdk.quests()

quests.startUserQuest(
    "<<QUEST ID>>",
    object : LiveLikeCallback<UserQuest>() {
        override fun onResponse(result: UserQuest?, error: String?) {
            error?.let{
                ...
            }
            result?.let {
                ...
            }
        }
    })

Getting UserQuest List

You can fetch all the userQuests started by a user.
This list is filterable by status and UserQuestIds
If you know a UserQuest id, you are able to get its details by using the code samples below. This can be useful if you would like to know the status of a UserQuest or the individual progress from each UserQuestTask.

let sdk: EngagementSDK
let questRequest = GetUserQuestsRequestOptions()

sdk.quests.getUserQuests(
  page: .first,
  options: questRequest
) { result in
   
   switch result {
   case .failure(let error):
    // handle error             
   case .success(let quests):
    // handle success        
   }
}
LiveLike.getUserQuests({ 
  profileId: "xxxxx", 
  status: "incomplete" //accepted values of status are "completed" & "incomplete"
  userQuestIds: ["123", "xyz"]
})
  .then(padinatedResponse => console.log(padinatedResponse.results))
quests = (application as LiveLikeApplication).sdk.quests()

quests.getUserQuests(
    GetUserQuestsRequestOptions(),
    LiveLikePagination.FIRST,
    object : LiveLikeCallback<LLPaginatedResult<UserQuest>>() {
        override fun onResponse(result: LLPaginatedResult<UserQuest>?, error: String?) {
            error?.let{
                ...
            }

            result?.let {
                ...
            }
        }
    }
)

Updating UserQuestTask Status

Status of UserQuestTasks can be updated using interface updateUserQuestTasks
This will go beyond and above the progress of that UserQuestTask

let sdk: EngagementSDK

sdk.quests.updateUserQuestTasks(
  userQuestID: "",
  userQuestTaskIDs: ["", ""],
  status: .completed
) { result in
   
   switch result {
   case .failure(let error):
    // handle error             
   case .success(let quests):
    // handle success        
   }
}
LiveLike.updateUserQuestTasks({ 
  userQuestId: "xxxxx", 
  userQuestTaskIds: ["123", "xyz"], 
  status: "completed" //accepted values of status are "completed" & "incomplete"
})
  .then(userQuest => console.log(userQuest))
quests = (application as LiveLikeApplication).sdk.quests()

quests.updateUserQuestTask(
    "<<USER QUEST ID>>",
    listOf(
            "<<TASK ID 1>>",
            "<<TASK ID 2>>"
        ),
    UserQuestStatus.completed,
    object : LiveLikeCallback<UserQuest>() {
        override fun onResponse(result: UserQuest?, error: String?) {
            error?.let{
                ...
            }
            result?.let {
                ...
            }
        }
    })

Updating UserQuestTask Progress

UserQuestTask progress can be updated by utilizing one of the two SDK interfaces.

  1. incrementUserQuestTaskProgress() can be used to increment progress by default or custom increment. A default increment is set up in the CMS.
  2. setUserQuestTaskProgress() can be used to set an overall progress of the UserQuestTask, which will overwrite any previously set value.
let sdk: EngagementSDK

// Increment by a custom increment by passing a value in `customIncrement` variable
// or set it to `nil` to use a default increment set up in the CMS
sdk.quests.incrementUserQuestTaskProgress(
  userQuestTaskID: "",
  customIncrement: nil // Pass a `nil` to increment by a default increment
) { result in
   
   switch result {
   case .failure(let error):
    // handle error             
   case .success(let userQuest):
    // handle success        
   }
}

// Set the overall progress of a `UserQuestTask`
// When set, previous progress will be overwritten 
sdk.quests.setUserQuestTaskProgress(
  userQuestTaskID: "",
  progress: 0.75
) { result in
    
   switch result {
   case .failure(let error):
    // handle error             
   case .success(let userQuest):
    // handle success        
   }
}
LiveLike.incrementUserQuestTaskProgress({ 
  userQuestTaskId, 
  customIncrement 
})
.then(userQuestTask => console.log(userQuestTask))

LiveLike.setUserQuestTaskProgress({ 
  userQuestTaskId, 
  customProgress 
})
.then(userQuestTask => console.log(userQuestTask))
quests.incrementUserQuestTaskProgress(
    "<<USER TASK ID>>",
    0.5f,
    object : LiveLikeCallback<UserQuestTask>() {
        override fun onResponse(result: UserQuestTask?, error: String?) {
            error?.let {
               ...
            }
            result?.let {
              ...  
            }
        }
    })
    
quests.setUserQuestTaskProgress(
    "<<USER TASK ID>>",
    0.5f,
    object : LiveLikeCallback<UserQuestTask>() {
        override fun onResponse(result: UserQuestTask?, error: String?) {
            error?.let{
                ...
            }
            result?.let {
                ...
            }
        }
    })