BadgeOS allows you to programmatically award an achievement to a user automatically, in more way than one. In most cases you’ll likely want to call badgeos_award_achievement_to_user(), which will simply give the user the achievement directly without verifying that they’ve earned it. If, however, you wanted to check and maybe award an achievement to the user (e.g. you’re not sure the user has met all the requirements) you can instead use badgeos_maybe_award_achievement_to_user().
You may also want to read through Understanding the Rules Engine to gain a more complete view of how this entire process works.
Awarding/Revoking Achievements
badgeos_award_achievement_to_user( $achievement_id, $user_id )
Directly award an achievement to a user, without checking whether they deserve it or not.
badgeos_revoke_achievement_from_user( $achievement_id , $user_id )
Revoke an achievement from a user, stripping it from their badgeos_earned_achievements usermeta. Note: this currently does not revoke their completed steps nor their earned points, but a hook is available that makes it possible for you to do both.
badgeos_maybe_award_achievement_to_user( $achievement_id, $user_id )
Check if user should earn an achievement, and award it if so. This function kicks off the BadgeOS “Rules Engine” which passes through several steps to determine first if a user has access to the achievement, and then if they satisfy all of its requirements. You can modify the rules that determine if a user has access or satisfies requirements using the filters referenced below.
Controlling how an achievement is earned (filters)
The following filters allow you to alter the standard earning procedure within BadgeOS.
badgeos_activity_triggers
Define additional hooks for BadgeOS to monitor for triggering achievements.
badgeos_user_deserves_trigger
Add or override rules for determining whether or not a user should get credit for triggering a hook
user_has_access_to_achievement
Add or override rules for determining whether or not a user has access to a given achievement
user_deserves_achievement
Add or override rules for determining whether or not a user may earn a given achievement
Performing other actions when an achievement is earned (actions)
The following action hooks are triggered when an achievement is awarded.
badgeos_award_achievement
This hook passes $user_id and $achievement_id every time an achievement is awarded to a user.
badgeos_revoke_achievement
This hook passes $user_id and $achievement_id every time an achievement is revoked from a user.
badgeos_unlock_{$achievement_type}
This hook passes $user_id and $achievement_id every time an achievement of a given type is awarded to a user.
badgeos_unlock_all_{$achievement_type}
This hook passes $user_id and $achievement_id when every achievement of a given type is awarded to a user.