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:

   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 hosted authentication submission object parameters

Objective-C SDK

// 'submission' is one of the BVBaseUGCSubmission objects, e.g., BVAnswerSubmission, BVReviewSubmission, etc.  
 submission.hostedAuthenticationEmail = "[email protected]"  
 submission.hostedAuthenticationCallback = "http://www.example.com/your/authentication-service"

// 'submission' is one of the BVBaseUGCSubmission objects, e.g., BVAnswerSubmission, BVReviewSubmission, etc.  
 submission.hostedAuthenticationEmail = @"[email protected]";  
 submission.hostedAuthenticationCallback = @"http://www.example.com/your/authentication-service";

Swift SDK

    answerSubmission 
          <+> action 
          <+> .hostedAuthEmail("[email protected]") 
          <+> .hostedAuthCallback(URL(string: http://www.example.com/your/authentication-service)) 
  

For more information regarding this step please refer to the Conversation API Authentication Tutorial.
For more information regarding each of the submission objects please also refer to the Content Submission documentation.

When to use

Use these parameters 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 BVBaseUGCSubmission 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=a7a4278ff33887d352fcdef0edd143f487dc

How to retrieve a bv_authtoken

You may setup your backend to retrieve the callback when the user opens the link in a browser and then send that bv_authtoken for the specific user via an out-of-band request, push notification, text message, etc. so that your application can utilize it.

How to retrieve a UAS

Once you have the bv_authtoken from the previous step, you can send off a BVUASSubmission which will return a BVUASSubmissionResponse via the success closure. From within the BVUASSubmissionResponse the userAuthenticationString property contains the BVSubmittedUAS object that provides the authenticatedUser property interface to obtain the actual UAS.

Objective-C SDK

var bv_authtoken: String = "..." // 'bv_authtoken' string value
let uasSubmission: BVUASSubmission = BVUASSubmission(bvAuthToken: bvAuthToken)
 
uasSubmission.submit({
    (response: BVUASSubmissionResponse) in
 
    // uas acquisition submitted successfully!
 
    if let uas: BVSubmittedUAS = response.userAuthenticationString,
        let authenticatedUser: String = uas.authenticatedUser {
            print("This is the actual UAS string value: \(authenticatedUser)")
        }
 
    // You should store authenticatedUser for the logged in user to make all future requests
    // setting the user property for subsequent submissions.
 
}) {
    (errors: [Error]) in
  // handle failure appropriately
}

NSString * bv_authtoken = @ "..."; // 'bv_authtoken' string value
BVUASSubmission * uasSubmission = [
    [BVUASSubmission alloc] initWithBvAuthToken: bv_authtoken
];
 
[uasSubmission submit: ^ (BVUASSubmissionResponse * _Nonnull response) {
 
        // uas acquisition submitted successfully!
 
        BVSubmittedUAS * uas = response.userAuthenticationString;
        if (uas & amp; & amp; uas.authenticatedUser) {
            NSLog(@ "This is the actual UAS string value: %@", uas.authenticatedUser);
        }
 
        // You should store authenticatedUser for the logged in user to make all future requests
        // setting the user property for subsequent submissions.
 
    }
    failure: ^ (NSArray * _Nonnull errors) {
 
        // handle failure appropriately
 
    }
];

Swift SDK

var bvAuthToken: String = "..." // 'bv_authtoken' string value
guard
let uasSubmission: BVUASSubmission = BVUASSubmission(bvAuthToken: bvAuthToken)
else {
    return
}
uasSubmission.handler {
        (result: BVConversationsSubmissionResponse < BVUAS > ) in
        if
        case let.failure(errors) = result {
            // handle failure appropriately
            return
        }
        guard
        case let.success(_, uasResponse) = result
        else {
            return
        }
        // uas acquisition submitted successfully!
        if let authenticatedUser = uasResponse.uas {
            print("This is the actual UAS string value: \(authenticatedUser)")
        }
    }
    .configure(configuration)
uasSubmission.async()

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 UAS authentication submission object parameters

Objective-C SDK

// 'submission' is one of the BVBaseUGCSubmission objects, e.g., BVAnswerSubmission, BVReviewSubmission, etc.  
 submission.user = "..." // authenticatedUser string value from previous step

 // 'submission' is one of the BVBaseUGCSubmission objects, e.g., BVAnswerSubmission, BVReviewSubmission, etc.  
 submission.user = @"..." // uas.authenticatedUser string value from previous step

Swift SDK

    (submission 
       <+> .uas("..."))  // authenticatedUser string value from previous step. 
  

For more information regarding each of the submission objects please also refer to the Content Submission documentation.

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 UAS authentication submission object parameters

Constructing the UAS authentication submission object parameters are done the same way as the last step of the Bazaarvoice-mastered authentication process.

How to get the UAS

You will need to implement this to be able to retrieve an encrypted User Authentication String (UAS) from your company's 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 follow these steps.