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:

1. Perform the following API request using your staging or production Conversations API key as appropriate:

   URL

   1. https:[stg.]api.bazaarvoice.com/data/submitreview.json?apiversion=5.4&passkey={YOUR_PASS_KEY}&productid=test1
   

2. 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

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,

1. The callbackUrl you provided here

2. A bv_authtoken query parameter generated by Bazaarvoice. You will use this to fetch a UAS. For example:

   http://www.example.com/your/authentication-service?bv_authtoken=a7a4278ff33887d352fcdef30edd143f487dc881

How to retrieve a bv_authtoken

You have multiple options for retrieving this bv_authtoken,

1. You may intercept the URL when it is tapped by the user on their phone by registering an IntentFilter in your AndroidManifest.xml. This will not work if the user taps/clicks on the link on a different device.
2. 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

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

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

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.