Peržiūrite versijai skirtą žinyno turinį:

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:

Note that awarding of badges is not enabled by default.

Įspėjimas:

The implementation structure visible in CRXDE Lite is subject to change once the UI becomes available.

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 located in the repository at 

  • /etc/community/badging/images

If stored in a different location, they should be read accessible by everyone.

Badges are differentiated in UGC as to 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

With the latest feature pack installed, the Communities Badges console provides the ability to 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

Role-based badges are assigned by an administrator to community members based on their role in the community.

Assigned (and awared) 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
       /etc/community/badging/images/moderator/jcr:content/moderator.png
  • group manager
       /etc/community/badging/images/group-manager/jcr:content/group-manager.png
  • privileged member
       /etc/community/badging/images/privileged-member/jcr:content/privileged-member.png
chlImage_1

Awarded Badges

Reward-based badges are awarded by the scoring service to community members based on rules applied to their activity in the community.

In order for badges to appear as a reward for activity, there are two things that must happen :

  • badging must be enabled for the feature component
  • scoring and badging rules must be applied to the page (or ancestor) on which the component is placed

Included in the release are three reward-based badges :

  • gold
       /etc/community/badging/images/gold-badge/jcr:content/gold.png
  • silver
       /etc/community/badging/images/silver-badge/jcr:content/silver.png
  • bronze
       /etc/community/badging/images/bronze-badge/jcr:content/bronze.png
chlImage_1

Pastaba:

Scoring rules may be configured to assign negative points for posts flagged as inappropriate and thus affect the score value.  However, once a badge is earned, it will not be automatically removed due to scoring point reduction or scoring rule changes.

Awarded badges may be revoked in the same manner as assigned badges.  See the Assign and Revoke Badges section.  Future improvements will include an UI to manage members’ 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

Scoring is not enabled by default.  The basic steps for setting up and enabling scoring and awarding of badges are :

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

To enable scoring and badges, add the properties scoringRules and badgingRules to to any node in the content tree for the site.  

If the site is already published, after applying all rules and enabling components, re-publish 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.

Property Type Description
badgingRules String[] an array list of badging rules
scoringRules String[] an array list of scoring rules

Pastaba:

If a scoring rule appears to have no effect on awarding badges, ensure the scoring rule has not been blocked by the badging rule's scoringRules property.  See the section titled Badging Rules.

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

chlImage_1

Pastaba:

Any component can be overlaid to display badges using the HBS code found in forums, QnA, and comments as an example.

Scoring Rules

Scoring rules are the foundation of scoring for the purpose of awarding badges.

Very simply, each scoring rule is a list of one or more sub-rules.  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 will invoke both rule1 and rule2
  • if both rules contain applicable sub-rules for the same topic/verb :
    • only the sub-rule from rule2 will affect the score
    • the scores from both sub-rules are not added together

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 sub-rules that define it.

Scores are stored in SRP.

Pastaba:

Best Practice : uniquely name each scoring rule.

Scoring rule names should be globally unique; they should not end with the same name.

An example of what not to do :
    /etc/community/scoring/rules/site1/forums-scoring
    /etc/community/scoring/rules/site2/forums-scoring

Scoring Sub-Rules

The scoring sub-rules contain the properties which detail the values for participating in the community.

Each scoring sub-rule 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 sub-rule specifies the owner of the content as receiving the points (forOwner).

Each sub-rule may be included in one or more scoring rules.

The name of the sub-rule typically follows the pattern of using a subject, object and verb.  For example:

  • member-comment-create
  • member-receive-vote

Sub-rules are nodes of type cq:Page with properties on its jcr:content node that specify the verbs and topics .

Property Type   Value Description
VERB Long
  • required; the verb corresponds to an event action
  • there must be at least one verb property
  • the verb must be entered all UPPERCASE
  • there can be multiple verb properties, but no duplicates
  • the value is the score to apply for this event
  • the value can be positive or negative
  • a list of verbs supported in the release is in the Topics and Verbs section
topics String[]
  • optional; restricts sub-rule to community components identified by event topics
  • if specified : value is multi-value string of event topics
  • a list of topics in the release is in the Topics and Verbs section
  • default is to apply to all topics associated with the verb(s)
forOwner Boolean
  • optional; not relevant when member is acting on content they own
  • if true, apply score to owner of content being acted upon
  • if false, apply score to member taking action
  • default is false
scoringType String
  • optional; identifies the scoring engine
  • if "basic", specifies the scoring engine based on quantity
    • included in the release
  • if "advanced", specifies the scoring engine based on quality and quantity
  • default is "basic"

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) :

  1. /etc/community/scoring/rules/comments-scoring
    • subRules[] =
      /etc/community/scoring/rules/sub-rules/member-comment-create
      /etc/community/scoring/rules/sub-rules/member-receive-vote
      /etc/community/scoring/rules/sub-rules/member-give-vote
      /etc/community/scoring/rules/sub-rules/member-is-moderated
  2. /etc/community/scoring/rules/forums-scoring
    • subRules[] =
      /etc/community/scoring/rules/sub-rules/member-forum-create
      /etc/community/scoring/rules/sub-rules/member-receive-vote
      /etc/community/scoring/rules/sub-rules/member-give-vote
      /etc/community/scoring/rules/sub-rules/member-is-moderated

Notes:

  • both rules and sub-rules nodes are of type cq:Page
  • subRules is an attribute of type String[] on the rule's jcr:content node
  • sub-rules may be shared among various scoring rules
  • rules should be located in a repository location with read permission for everyone
    • rule names must be unique regardless of location

Activating Custom Scoring Rules

Any changes or additions made to scoring rules or sub-rules made in the author environment need to be installed on publish.

Badging Rules

Badging rules link scoring rules to badges by specifying :

  • which scoring rule
  • the score necessary to be awared 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|/etc/community/badging/images/bronze-badge/jcr:content/bronze.png
    • a bronze badge is awared for earning 1 point
  • 60|/etc/community/badging/images/silver-badge/jcr:content/silver.png
    • a silver badge is awarded when 60 points have been accumulated
  • 80|/etc/community/badging/images/gold-badge/jcr:content/gold.png
    • a gold badge is awared 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.

Pastaba:

Best practice : create badge images unique to each AEM site.

chlImage_1
Property Type Value Description
thresholds String[] (required) A multi-value string of the form 'number|path'
  • number = score
  • | = the vertical line char (U+007C)
  • path = full path to badge image resource
The strings must be ordered so that the numbers are increasing in value and no whitespace should appear between the number and path.
Example entry :
80|/etc/community/badging/images/gold-badge/jcr:content/gold.png
badgingType String (optional)  Identifies the scoring engine as either "basic" or "advanced".  If the advanced scoring engine is desired, see (Beta) Advanced Scoring and Badges.
Default is "basic".
scoringRules String[] (optional)  A multi-value string to restrict the badging rule to scoring events identified by the scoring rules

Included Badging Rules

Included in the release are two Badging Rules that correspond to the Forums and Comments Scoring Rules.

  • /etc/community/badging/rules/comments-badging
  • /etc/community/badging/rules/forums-badging

Notes:

  • rules nodes are of type cq:Page
  • rules should be located in a repository location with read permission for everyone
    • rule names must be unique regardless of location

Activating Custom Badging Rules

Any changes or additions made to badging rules or images made in the author environment need to be installed on publish.

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 : /etc/community/badging/images/moderator/jcr:content/moderator.png

member-profile-url = the endpoint for the member's profile on publish
  for example : http://<server>:<port>/home/users/community/riley/profile.social.json

Pastaba:

The member-profile-url

Examples :

Assign a moderator badge

curl -i -X POST -H "Accept:application/json" -u admin:admin -F ":operation=social:assignBadge" -F "badgeContentPath=/etc/community/badging/images/moderator/jcr:content/moderator.png" http://localhost:4503/home/users/community/updcs9DndLEI74DB9zsB/profile.social.json

Revoke an assigned silver badge

curl -i -X POST -H "Accept:application/json" -u admin:admin -F ":operation=social:deleteBadge" -F "badgeContentPath=/etc/community/badging/images/silver/jcr:content/silver.png" http://localhost:4503/home/users/community/updcs9DndLEI74DB9zsB/profile.social.json

Pastaba:

Using cURL to assign and revoke badges works for any badge image, but when assigned instead of earned, they are marked as assigned badges and handled accordingly.

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

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 in the releae, the following tables describe the verbs defined for each topic available for use in scoring sub-rules.

Pastaba:

A new boolean property, allowBadges, enables/disables the display of badges for a component instance.  It will be configurable in updated component edit dialogs through a checkbox labeled Display Badges.

Calendar Component
SocialEvent topic = com/adobe/cq/social/calendar

Verb Description
POST member creates a calendar event
ADD member comments on a calendar event
UPDATE member's calendar event or comment is edited
DELETE member's calendar event or comment is deleted

 

Comments Component
SocialEvent topic = com/adobe/cq/social/comment

Verb Description
POST member creates a comment
ADD member replies to comment
UPDATE member's comment is edited
DELETE member's comment is deleted

 

File Library Component
SocialEvent topic = com/adobe/cq/social/fileLibrary

Verb Description
POST member creates a folder
ATTACH member uploads a file
UPDATE member updates a folder or file
DELETE member deletes a folder or file

 

Forum Component
SocialEvent topic = com/adobe/cq/social/forum

Verb Description
POST member creates forum topic
ADD member replies to forum topic
UPDATE member's forum topic or reply is edited
DELETE member's forum topic or reply is deleted

 

Journal Component
SocialEvent topic = com/adobe/cq/social/journal

Verb Description
POST member creates a blog article
ADD member comments on a blog article
UPDATE member's blog article or comment is edited
DELETE member's blog article or comment is deleted

 

QnA Component
SocialEvent topic = com/adobe/cq/social/qna

Verb Description
POST member creates a QnA question
ADD member creates a QnA answer
UPDATE member's QnA question or answer is edited
SELECT member's answer is selected
UNSELECT member's answer is de-selected
DELETE member's QnA question or answer is deleted

 

Reviews Component
SocialEvent topic = com/adobe/cq/social/review

Verb Description
POST member creates review
UPDATE member's review is edited
DELETE member's review is deleted

 

Rating Component
SocialEvent topic = com/adobe/cq/social/tally/rating

Verb Description
ADD RATING member's content has been up rated
REMOVE RATING member's content has been down rated

 

Voting Component
SocialEvent topic = com/adobe/cq/social/tally/voting

Verb Description
ADD VOTING member's content has been up voted
REMOVE VOTING member's content has been down voted

 

Moderation-enabled Components
SocialEvent topic = com/adobe/cq/social/moderation

Verb Description
DENY member's content is denied
FLAG-AS-INAPPROPRIATE member's content is flagged
UNFLAG-AS-INAPPROPRIATE member's content is unflagged
ACCEPT member's content is approved by moderator
CLOSE member closes comment to edits and replies
OPEN member re-opens comment

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 would need 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

Badges are not appearing

If scoring and badging rules have been applied to the web site's content, but badges are not being awared for any activity, ensure badges have been enabled for that component's instance.

See Enable Badges for Component.

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

Most of the properties and values, especially the verbs, are case-sensitive.  Verbs must be all UPPERCASE when used in a scoring sub-rule.  

If the feature is not working as expected, ensure the data has been correctly entered.

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 /etc/community/badging/rules/forums-badging
    • select +
    • enter /etc/community/badging/rules/comments-badging
    • select OK
  • add the scoringRules property :
    • Name : scoringRules
    • Type : String
    • select Multi
    • select Add
    • enter /etc/community/scoring/rules/forums-scoring
    • select +
    • enter /etc/community/scoring/rules/comments-scoring
    • select OK
  • select Save All
chlImage_1

Next ensure 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
chlImage_1

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.

chlImage_1

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.

Šis darbas yra licencijuotas pagal licenciją „Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License“  „Twitter™“ ir „Facebook“ skelbimams „Creative Commons“ sąlygos netaikomos.

Teisiniai pranešimai   |   Privatumo internete politika