Badges & Custom Badges

Badges will be displayed next to the user's display name. Different user types may be perceived differently by users wanting to join the conversation, and these badges provide a little bit more insight into who represents what. The following badges are readily available:

Author

This badge is designated by the site admin who will be able to badge the author of the article, so that users will know when the author chooses to comment or engage with other users onsite.

To integrate with our owner tagging system a small amount of metadata should be present on the page. The owner (or author) of the page is detected automatically on pages with Viafoura JavaScript with the following tags; any of the following will work:

<meta name=”vf:owner” content=”...” />
<meta property=”vf:owner” content=”...” />
<meta name=”vf:author” content=”...” />
<meta property=”vf:author” content=”...” />

To represent multiple values, you are required to add multiple vf:owner tags. Please only use one of vf:owner or vf:author; never use both.

<meta property=”vf:owner” content=”[VF_USER_ID]” />
<meta property=”vf:owner” content=”[VF_USER_ID]” />

Valid examples:

<meta property=”vf:owner” content=”viafoura-id:8740034942” />
<meta property=”vf:owner”content=”loginradius:ebf789c2-1234-1234-1234-adcbef232784” />
<meta property=”vf:owner” content=”facebook:8723873287327823” />

📘

Note

If using a third party id. Here are the supported values:

cookie (For custom cookie login)
oidc (For OpenID Connect (OIDC))
janrain
loginradius
apple
facebook
google
linkedin
microsoft
twitter
yahoo

Trusted User

Assigned by site administrators to users who have been actively engaged and whom are believed to have, and will continue to make meaningful contributions to the community

Trusted users have a special icon beside their name which allows for a few benefits:
They receive an icon that displays beside their name
They bypass moderation filters
They bypass spam filters

Moderator

Assigned by site administrators to a person who will monitor conversations for bad language, inappropriate content, etc.

Custom

The Custom Badge can be created for specific needs such as a subscriber badge, premium badge, etc. To learn more, visit the Profile section of our APIs.

Make an API Call

1. Obtain API credentials
   A client ID and secret pair with the appropriate permission levels will be provided to you by your client success representative. (please contact our support team).

2. Create a JSON Web token (JWT)
   Use the Client ID and Secret to call the endpoint below and generate a JWT to use as authorization for Viafoura API calls (https://documentation.viafoura.com/reference#authorization). For this endpoint, the authentication header when passing your credentials should be BASIC.

📘

Note

• Each JWT is valid only for 5 minutes.

3. To call any other Viafoura API endpoints, set the authentication header to BEARER and use the generated JWT as the value.

Create a new badge

Make an API call to the Create or Update Badge API endpoint (https://documentation.viafoura.com/reference/createorupdatebadge), using the JWT created in the step prior as authentication.

The payload must contain:
• label: the internal name of the badge, used in requests to assign badges to users
• description: Text of badge to be shown on the UI

{
"label": "pay_subscriber",
"description": "Paywall Subscriber"
}

Remove a badge

Make an API call to the Remove Badge API endpoint (https://documentation.viafoura.com/reference/removeexistingbadge), using the JWT created in the step prior as authentication.

The payload must contain:
• label: the internal name of the badge

{
"label": "pay_subscriber"
}

Assign a badge to a user

Make an API call to the Assign Badge API endpoint (https://documentation.viafoura.com/reference/assignbadgetouser), using the JWT created in the step prior as authentication.

📘

Note

The request may return 401/403 error if the token is no longer valid, 400 if the label does not exist or 200 if successful. The request does not return any payload in the response.

Only one user is allowed per request.

The payload must contain:
• third party id of the user or the uuid of a viafoura user
• badge label (must be pre-existing)
• third party type string, if using a third party id. Here are the supported values:

• cookie (For custom cookie login)
• oidc (For OpenID Connect (OIDC))
• janrain
• loginradius
• apple
• facebook
• google
• linkedin
• microsoft
• twitter
• yahoo

❗️

Note

Your authentication workflow will be leveraging either a third party service or Viafoura's out-of-the-box ID Management. You will need to include in the API call either the 'thirdparty_id' (if you are using a third party service) or the 'user_uuid' (if you are using Viafoura's system).

Adding both user identifiers to the call will result in an error.

Examples:

with third party user id

{
"third_party_user_id": "cookie login - third party id",
"third_party_type": "cookie",
"label": "subscriber"
}

with Viafoura user id

{
"user_uuid": "c1f19e1f-55a4-4792-b92f-6c64f57f6e27",
"label": "subscriber"
}

Assign badges automatically

You can assign badges automatically in response to user actions in your community. This is achieved by the use of VF webhooks.

How it works?

1. VF emits webhook events in response to user actions (likes/dislikes/new comments/etc) You can see the full list here:
2. Your backend service receives those actions and assigns badges according to your logic.

📘

Note

You need to reach out to your VF customer success representative to enable webhooks to your backend service to properly receive events.

Full implementation example: here