Authentication
This documentation explains how to authenticate authors using either Bazaarvoice-mastered authentication ("hosted auth") or Client-mastered authentication ("site auth").
Introduction
When a user wants to submit user-generated content (UGC), we need to verify that the user is who they say they are, and that they consent to their UGC being published. In order to do this a User Authentication String is required with all Submission Requests. Depending on your configuration, you will create/retrieve this UAS is one of two ways: Bazaarvoice-mastered Authentication, or Client-mastered Authentication.
Determine your authentication method
See how to determine your authentication configuration to learn which method you are configured for.
OR
Follow the steps described below:
-
Perform the following API request using your staging or production Conversations API key as appropriate:
1. https:[stg.]api.bazaarvoice.com/data/submitreview.json?apiversion=5.4&passkey={YOUR_PASS_KEY}&productid=test1
-
If you find
hostedauthentication
in the response, then you are configured for Bazaarvoice-mastered authentication. If not, then you should use Client-mastered authentication.
Bazaarvoice-mastered authentication
In this authentication type, authors do not login to your site prior to submission. Instead, they authenticate by providing an email address with their submission. User IDs are created by the Bazaarvoice authentication system, which is considered to be the authoritative (master) source for user identification, and are associated with the email addresses. Bazaarvoice-mastered authentication is also referred to as "Bazaarvoice-hosted authentication" because Bazaarvoice manages the user IDs.
Stage 1: App does not have a UAS for the user yet
How to construct the AuthenticationProvider
AuthenticationProvider
final AuthenticationProvider authProvider = new BVHostedAuthenticationProvider(userEmailAddress, callbackUrl);
When to use
Use this constructor if you have not managed to retrieve the User Authentication String (UAS) for the user. This method will send the user an email to confirm the ConversationsSubmissionRequest
that this was attached to. The email will contain a link for them to tap to confirm, and it will be composed of,
-
The
callbackUrl
you provided here -
A
bv_authtoken
query parameter generated by Bazaarvoice. You will use this to fetch a UAS. For example:
How to retrieve a bv_authtoken
bv_authtoken
You have multiple options for retrieving this bv_authtoken
,
- You may intercept the URL when it is tapped by the user on their phone by registering an
IntentFilter
in yourAndroidManifest.xml
. This will not work if the user taps/clicks on the link on a different device. - You may setup your backend to retrieve the callback when the user opens the link in a browser, and then send a push notification to your app for this specific user, with the
bv_authtoken
.
How to retrieve a UAS
UAS
Once you have the bv_authtoken
from the previous step, you can send off a UserAuthenticationStringRequest
, which will return a UserAuthenticationStringResponse
. You can then obtain the UAS
by calling, UserAuthenticationStringResponse#getUas()
. You should store this for the logged in user to make all future requests with the BVHostedAuthenticationProvider(String uas)
constructor.
What if I do not send a UAS?
All content will still be submitted and moderated, and will show up in the display requests.
The consequences for not retrieving the UAS, and using the other constructor, is that the user will continue to be sent an email to confirm for each submission.
The consequences for a user not confirming their submission is that their user profile will not be merged with the content they submitted. If at any point in the future, your app is able to send a UAS then all of those cumulative profiles will be merged.
Stage 2: App has a UAS for the user
How to construct the AuthenticationProvider
AuthenticationProvider
final AuthenticationProvider authProvider = new BVHostedAuthenticationProvider(uas);
When to use
Use this constructor if you managed to retrieve the UAS for the user.
Client-mastered authentication
In this authentication type, authors must login to your system prior to submission. User IDs are created by your authentication system, which is considered to be the authoritative (master) source for user identification, and are submitted to Bazaarvoice along with the author's content. Client-mastered authentication is also referred to as "Client-site authentication" because it relies on your site's authentication system.
How to construct the AuthenticationProvider
AuthenticationProvider
final AuthenticationProvider authProvider = new SiteAuthenticationProvider(uas);
How to get the UAS
You will need to implement this to be able to retrieve an encrypted User Authentication String (UAS) from your companies backend.
Your company may have an existing endpoint to retrieve this from, if your web team has already implemented this. If not you will need to these steps.
Updated 8 months ago