Communities Scoring and Badges communities-scoring-and-badges
Overview overview
The AEM Communities scoring and badges feature provides the ability to identify and reward community members.
The main aspects of scoring and badges are:
-
Assign badges to identify the role of a member in the community.
-
Basic awarding of badges to members to encourage their participation (quantity of content created).
-
Advanced awarding of badges to identify members as experts (quality of content created).
Note that awarding of badges is not enabled by default.
Badges badges
Badges are placed under a member’s name to indicate either their role or their standing in the community. Badges may either be displayed as an image or as a name. When displayed as an image, the name is included as alternate text for accessibility.
By default, badges are in the repository at the following:
/libs/settings/community/badging/images
If stored in a different location, they should be read accessible by everyone.
Badges are differentiated in UGC whether they were assigned or were earned according to the rules. Presently, assigned badges appear as text and earned badges appear as an image.
Badge Management UI badge-management-ui
The Communities Badges console lets you add custom badges which can be displayed for a member when earned (awarded) or when they take on a specific role in the community (assigned).
Assigned Badges assigned-badges
Role-based badges are assigned by an administrator to community members based on their role in the community.
Assigned (and awarded) badges are stored in the selected SRP and are not directly accessible. Until a GUI is available, the only means for assigning role-based badges is to do so with code or cURL. For cURL instructions, see the section titled Assign and Revoke Badges.
Included in the release are three role-based badges:
-
moderator
/libs/settings/community/badging/images/moderator/jcr:content/moderator.png
-
group manager
/libs/settings/community/badging/images/group-manager/jcr:content/group-manager.png
-
privileged member
/libs/settings/community/badging/images/privileged-member/jcr:content/privileged-member.png
Awarded Badges awarded-badges
Reward-based badges are awarded by the scoring service to community members based on rules applied to their activity in the community.
For badges to appear as a reward for activity, there are two things that must happen:
Included in the release are three reward-based badges:
-
gold
/libs/settings/community/badging/images/gold-badge/jcr:content/gold.png
-
silver
/libs/settings/community/badging/images/silver-badge/jcr:content/silver.png
-
bronze
/libs/settings/community/badging/images/bronze-badge/jcr:content/bronze.png
Custom Badges custom-badges
Custom badges can be installed using the Badges console and either assigned or specified in badging rules.
When installed from the Badges console, custom badges are automatically replicated to the publish environment.
Enable Scoring enable-scoring
Scoring is not enabled by default. The basic steps for setting up and enabling scoring and awarding of badges are:
-
Identify rules for earning points (scoring rules).
-
For points accumulated per scoring rules, assign badges (badging rules).
See the Quick Test section to enable scoring for a community site using the default scoring and badging rules for forums and comments.
Apply Rules to Content apply-rules-to-content
To enable scoring and badges, add the properties scoringRules
and badgingRules
to any node in the content tree for the site.
If the site is already published, after applying all rules and enabling components, republish the site.
The rules that apply to a badging-enabled component are those for the current node or its ancestor.
If the node is of type cq:Page
(recommended), then using CRXDE|Lite, add the properties to its jcr:content
node.
Enable Badges for Component enable-badges-for-component
The scoring and bading rules are in effect only for instances of components that have enabled badging by editing the component configuration in authoring mode.
A boolean property, allowBadges
, enables/disables the display of badges for a component instance. It is configurable in the component edit dialog for forum, QnA, and comment components through a checkbox labeled Display Badges.
Example : allowBadges for Forum component instance example-allowbadges-for-forum-component-instance
Scoring Rules scoring-rules
Scoring rules are the foundation of scoring for awarding badges.
Each scoring rule is a list of one or more subrules. Scoring rules are applied to the community site content to identify the rules to apply when badges are enabled.
Scoring rules are inherited but not additive. For example:
-
If page2 contains scoring rule2 and its ancestor page1 contains scoring rule1.
-
An action on a page2 component invokes both rule1 and rule2.
-
If both rules contain applicable subrules for the same
topic/verb
:- Only the subrule from rule2 affects the score.
- The scores from both subrules are not added.
When there is more than one scoring rule, the scores are maintained separately for each rule.
Scoring rules are nodes of type cq:Page
with properties on its jcr:content
node that specify the list of subrules that define it.
Scores are stored in SRP.
/libs/settings/community/scoring/rules/site2/forums-scoring
Scoring Sub-Rules scoring-sub-rules
The scoring subrules contain the properties which detail the values for participating in the community.
Each scoring subrule identifies:
- What activities are being tracked?
- Which specific community function is involved?
- How many points are awarded?
By default, points are awarded to the member taking action unless the subrule specifies the owner of the content as receiving the points ( forOwner
).
Each subrule may be included in one or more scoring rules.
The name of the subrule typically follows the pattern of using a subject, object, and verb. For example:
- member-comment-create
- member-receive-vote
Subrules are nodes of type cq:Page
with properties on its jcr:content
node that specify the verbs and topics .
Included Scoring Rules and Sub-Rules included-scoring-rules-and-sub-rules
Included in the release are two scoring rules for the Forum Function (one each for the Forum and Comments components of the Forum feature) :
-
/libs/settings/community/scoring/rules/comments-scoring
- subRules[] =
/libs/settings/community/scoring/rules/sub-rules/member-comment-create
/libs/settings/community/scoring/rules/sub-rules/member-receive-vote
/libs/settings/community/scoring/rules/sub-rules/member-give-vote
/libs/settings/community/scoring/rules/sub-rules/member-is-moderated
- subRules[] =
-
/libs/settings/community/scoring/rules/forums-scoring
- subRules[] =
/libs/settings/community/scoring/rules/sub-rules/member-forum-create
/libs/settings/community/scoring/rules/sub-rules/member-receive-vote
/libs/settings/community/scoring/rules/sub-rules/member-give-vote
/libs/settings/community/scoring/rules/sub-rules/member-is-moderated
- subRules[] =
Notes:
-
Both
rules
andsub-rules
nodes are of type cq:Page. -
subRules
is an attribute of type String[] on the rule’sjcr:content
node. -
sub-rules
may be shared among various scoring rules. -
rules
should be in a repository location with read permission for everyone.- Rule names must be unique regardless of the location.
Activating Custom Scoring Rules activating-custom-scoring-rules
Any changes or additions made to scoring rules or subrules made in the author environment must be installed on publish.
Badging Rules badging-rules
Badging rules link scoring rules to badges by specifying:
- Scoring rule
- Score necessary to be awarded a specific badge
Badging rules are nodes of type cq:Page
with properties on its jcr:content
node that correlate scoring rules to scores and badges.
The rules for badging consist of a mandatory thresholds
property that is an ordered list of scores mapped to badges. The scores must be ordered in increasing value. For example:
-
1|/libs/settings/community/badging/images/bronze-badge/jcr:content/bronze.png
- A bronze badge is awarded for earning one point.
-
60|/libs/settings/community/badging/images/silver-badge/jcr:content/silver.png
- A silver badge is awarded when 60 points have been accumulated.
-
80|/libs/settings/community/badging/images/gold-badge/jcr:content/gold.png
- A gold badge is awarded when 80 points have been accumulated.
Badging rules are paired with scoring rules, which determine how points accumulate. See the section titled Apply Rules to Content.
The scoringRules
property on a badging rule simply restricts which scoring rules can be paired with that particular badging rule.
Included Badging Rules included-badging-rules
Included in the release are two Badging Rules that correspond to the Forums and Comments Scoring Rules.
-
/libs/settings/community/badging/rules/comments-badging
-
/libs/settings/community/badging/rules/forums-badging
Notes:
-
rules
nodes are of type cq:Page. -
rules
should be in a repository location with read permission for everyone.- Rule names must be unique regardless of location.
Activating Custom Badging Rules activating-custom-badging-rules
Any changes or additions made to badging rules or images made in the author environment must be installed on publish.
Assign and Revoke Badges assign-and-revoke-badges
Badges may be assigned to members either using the members console or programmatically using cURL commands.
The following cURL commands show what is necessary for an HTTP request for assigning and revoking badges. The basic format is:
cURL -i -X POST -H header -u signin -F operation -F badge member-profile-url
header = “Accept:application/json”
custom header to pass to server (required)
signin = administrator-id:password
for example, admin:admin
operation = “:operation=social:assignBadge” OR “:operation=social:deleteBadge”
badge = “badgeContentPath=badge-image-file”
badge-image-file = the location of the badge image file in the repository
for example, /libs/settings/community/badging/images/moderator/jcr:content/moderator.png
member-profile-url = the endpoint for the member’s profile on publish
for example, https://<server>:<port>/home/users/community/riley/profile.social.json
- May refer to an author instance if the Tunnel Service is enabled.
- May be an obscure, random name - see Security Checklist regarding authorizable ID.
Examples: examples
Assign a moderator badge assign-a-moderator-badge
curl -i -X POST -H "Accept:application/json" -u admin:admin -F ":operation=social:assignBadge" -F "badgeContentPath=/libs/settings/community/badging/images/moderator/jcr:content/moderator.png" /home/users/community/updcs9DndLEI74DB9zsB/profile.social.json
Revoke an assigned silver badge revoke-an-assigned-silver-badge
curl -i -X POST -H "Accept:application/json" -u admin:admin -F ":operation=social:deleteBadge" -F "badgeContentPath=/libs/settings/community/badging/images/silver/jcr:content/silver.png" /home/users/community/updcs9DndLEI74DB9zsB/profile.social.json
Scoring and Badges for Custom Components scoring-and-badges-for-custom-components
Scoring and badging rules may be created for custom components by associating the event topics created for the component with verbs.
Topics and Verbs topics-and-verbs
When members interact with communities features, events are sent that can trigger asynchronous listeners, like notifications and scoring.
A component’s SocialEvent instance records the events as actions
that occur for a topic
. The SocialEvent includes a method to return a verb
associated with the action. There is an n-1 relationship between actions
and verbs
.
For the communities components delivered, the following tables describe the verbs
defined for each topic
available for use in scoring subrules.
allowBadges
, enables/disables the display of badges for a component instance. It is configurable in updated component edit dialogs through a checkbox labeled Display Badges.Calendar Component
SocialEvent topic
= com/adobe/cq/social/calendar
Comments Component
SocialEvent topic
= com/adobe/cq/social/comment
File Library Component
SocialEvent topic
= com/adobe/cq/social/fileLibrary
Forum Component
SocialEvent topic
= com/adobe/cq/social/forum
Journal Component
SocialEvent topic
= com/adobe/cq/social/journal
QnA Component
SocialEvent topic
= com/adobe/cq/social/qna
Reviews Component
SocialEvent topic
= com/adobe/cq/social/review
Rating Component
SocialEvent topic
= com/adobe/cq/social/tally/rating
Voting Component
SocialEvent topic
= com/adobe/cq/social/tally/voting
Moderation-enabled Components
SocialEvent topic
= com/adobe/cq/social/moderation
Custom Component Events custom-component-events
For a custom component, a SocialEvent is instantiated to record the component’s events as actions
that occur for a topic
.
To support scoring, the SocialEvent needs to override the method getVerb()
so that an appropriate verb
is returned for each action
. The verb
returned for an action may be one commonly used (such as POST
) or one specialized for the component (such as ADD RATING
). There is an n-1 relationship between actions
and verbs
.
Troubleshooting troubleshooting
Badges are not appearing badges-are-not-appearing
If scoring and badging rules have been applied to the web site’s content, but badges are not being awarded for any activity, ensure that badges have been enabled for that component’s instance.
See Enable Badges for Component.
Scoring rule has no effect scoring-rule-has-no-effect
If scoring and badging rules have been applied to the web site’s content, and badges are being awarded for some actions, but not others, check that the badging rule has not restricted the scoring rules to which it applies.
See the scoringRules
property of Badging Rules.
Case Sensitive Typo case-sensitive-typo
Most of the properties and values, especially the verbs, are case-sensitive. Verbs must be all UPPERCASE when used in a scoring subrule.
If the feature is not working as expected, ensure that the data has been correctly entered.
Quick Test quick-test
It is possible to quickly try scoring and badging using the Getting Started Tutorial (engage) site :
-
Access CRXDE Lite on author.
-
Browse to the base page:
- /content/sites/engage/en/jcr:content
-
Add the badgingRules property:
- Name:
badgingRules
- Type:
String
- Select Multi
- Select Add
- Enter
/libs/settings/community/badging/rules/forums-badging
- Select +
- Enter
/libs/settings/community/badging/rules/comments-badging
- Select OK
- Name:
-
Add the scoringRules property:
- Name:
scoringRules
- Type:
String
- Select Multi
- Select Add
- Enter
/libs/settings/community/scoring/rules/forums-scoring
- Select +
- Enter
/libs/settings/community/scoring/rules/comments-scoring
- Select OK
- Name:
-
Select Save All.
Next, ensure that the forum and comments components allow badges to be displayed:
-
Again using CRXDE Lite.
-
Browse to the forum component
/content/sites/engage/en/forum/jcr:content/content/primary/forum
-
Add allowBadges boolean property, if necessary, and ensure it is true.
- Name:
allowBadges
- Type:
Boolean
- Value:
true
- Name:
Next, republish the community site.
Finally,
-
Browse to the component on the publish instance.
-
Sign in as a community member (for example, weston.mccall@dodgit.com / password).
-
Post a new forum topic.
-
The page must be refreshed for the badge to show.
- Logout and login as a different community member (for example: aaron.mcdonald@mailinator.com/password).
-
Select the Forum.
This should earn the community member a bronze badge visible with their forum post due to the first forums-badging rule’s first threshold being a score of 1.
Additional Information additional-information
More information may be found on the Scoring and Badges Essentials page for developers.
For information on the advanced scoring engine, see Advanced Scoring and Badges.
The configurable Leaderboard component and function simplifies the display of members and their scores on a community site.