Connecting your listings to Google Business Profile

Building the connect flow

In order to connect your listings with Uberall, you only need to link to the following destination:

https://$YOUR_DOMAIN/en/app/$YOUR_WHITELABEL_PATH/google/connect?secret=$CONNECT_SECRET&id=$LOCATION_ID&language=$LANGUAGE&redirectTo=$REDIRECT_TO

The parameters are defined as follows:

• $YOUR_DOMAIN: The domain where you are running the Uberall application
• $YOUR_WHITELABEL_PATH: The whitelabel url path you have defined with your Partner Growth Manager for the Uberall application
• $CONNECT_SECRET: listing.connectSecret, returned in the location details call. Note that this secret expires, so you should retrieve it only prior to showing it and using it in your application.
• $LOCATION_ID: the ID of the location for which you are connecting a google account/page
• $REDIRECT_TO: where the flow should redirect you after the entire flow is finished (e.g. connect to google, select page, confirm selection). This should typically be a success page on your end

After this, your listing will be connected and the Uberall application will have access to it.

In case of an error

In the case of an error, a query parameter will be added onto the end of the redirectTo url, of the format https://example.com?errorCode=$errorCode, where possible error codes are:

• MISSING.googleCode - missing GBP OAuth code (wrong link, incorrect URL, ...). Restart the connect flow from scratch.
• INVALID.googleCode - invalid GBP OAuth code (maybe the link is expired). Restart the connect flow from scratch.
• MISSING.googleAccount - for some reason, the GoogleAccount that was previously created is gone. That should not happen (maybe the ID is wrong? or the token doesn't manage that account (anymore)?).
• NOT_CONNECTED - no GoogleAccount could be found for that listing. Maybe the user got a (old) link too far into the flow and the account is invalid now. Restart the connect flow from scratch.
• INVALID.id - the id parameter (corresponding to the Uberall location id) is required and is missing or doesn't match any location/listing, or the connect secret doesn't match with the passed id.
• MISSING.pageId - the pageId parameter (corresponding to the location id on Google’s side) is missing.
• MISSING.whitelisted.redirectUrl - trying to redirect to a domain that is outside of the structure of your website. You would need to provide a list of domains to be whitelisted and to enable redirection. The domains need to be set on SP level

• INVALID.pageId - the pageId parameter (corresponding to the location id on Google’s side) is incorrect (it doesn't exist in the GBP account).
• noMethod - there is no verification method for that listing, or the chosen verification method is no longer available, so we cannot perform verification via the API (it's an issue on Google’s side).

So e.g. if your redirectTo url is https://example.com, and there is an error with the listing that is passed to the initial popup, you will be redirected to https://example.com?errorCode=INVALID.id.

Checking the connection status of a listing

The Uberall API is providing you with all the necessary information, to find out whether a location needs to be connected or is already being managed by Uberall.

• Call /api/locations/$LOCATION_ID/google/page to get the status of the current Google page
• If this call returns with HTTP status code 400, your listing is not connected yet and you get one of the following responses:
  • NO_ACCOUNT_CONNECTED – In this case, the user did not connect any Google account.
  • ACCOUNT_WAITING_FOR_AUTO_PAGE_SELECT – In this case, the user connected a Google account on a business level (meaning, all existing and future locations in that business will automatically be connected to the same account). The app is in the process of auto selecting a page or creating a new one.
  • NO_PAGE_SELECTED – In this case, the user has connected a Google account but has not yet selected a Google page or created one for the location.
  • PAGE_NOT_CREATED – In this case, the user has connected a Google and account and chosen to create a new page. The app is in the process of creating it.
  • PAGE_CLAIMED_BY_OTHERS – In this case, an existing verified page for this location was found on Google. The user can either connect the correct account managing the page, or request admin rights to it.
  • PAGE_IN_REVIEW - In this case, the data were not accepted by Google and need to be manually reviewed. The Google page cannot be created or updated in the meantime.

Implementation best practices

Here is how the flow behaves in the application:

• Open popup with with proper URL and redirect target
• Show the whole flow in a popup window, then redirect it to a success page within the popup
• The popup in return communicates with the parent page (see below for code samples), gives back the appropriate return codes taken from the params of the redirect.
• If using this flow, the key is that the $REDIRECT_TO url is on the same domain as wherever the flow was started, e.g. uberall.com. That way the two windows can securely communicate with one another.

Code Sample for communicating with the popup

We are using the Javascript browser postMessage API (https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) to communicate from the popup window back to the parent window. When we first create the popup we register an event listener

window.addEventListener("message", callback);

The listener will handle the popup window's response. Then in the popup window, the final page (i.e. our success page defined in redirectTo) posts a message to the parent like so:

var errorCode = "${params.errorCode}";


function parseParams() {
    var obj = {}, key_value, key;
    window.location.search.substr(1).split("&").forEach(function (keyValue) {
        if (keyValue) {
            key_value = keyValue.split("=");
            key = decodeURIComponent(key_value[0]);
            if (typeof key !== "undefined") {
                var val = typeof key_value[1] !== "undefined" ? decodeURIComponent(key_value[1]) : true;
                obj[key] = val;
            }
        }
    });
    return obj;
}


function post(opts) {
    window.opener.postMessage({
        success: opts.success,
        error: opts.error
    }, location.origin);
}


if (!window.opener) {
    console.log("NO PARENT");
} else {
    post(parseParams());


    if (!errorCode) {
        setTimeout(window.close, 3000)
    }
}


$(".close-popup-link").on("click", function(event) {
    event.preventDefault();


    window.close();
});

The key there is in the

window.opener.postMessage()

block, where we can pass either a success or error message the parent page. In our case, on success, we re-fetch the location and update the listings view for Google to show that there is now a connected location.

Screenshots of the flow (using a popup)

Splash page

Oauth connect of the Google account with the Uberall app:

Giving rights to the Uberall app called Local Listing Connector.

Choose the location group

Question whether this account can be used for all locations of this business (shown only if the connected account is VERIFIED). This use case mostly applies to chains and enterprises.

Choose the listing that has to be connected or opting for creating a new one.

Verification

Choose method

Url: https://$YOUR_DOMAIN/en/app/$YOUR_WHITELABEL_PATH/google/verification?id=$LOCATION_ID&secret=$CONNECT_SECRET&language=$LANGUAGE&redirectTo=$REDIRECT_TO

Verify by phone (either call or SMS)

Verify by email. Depending on what Google allows, the “hello” portion may be editable by the user)

Verify by address (postcard). The contact name needs to be provided by the user.

Enter PIN for verification

When a verified profile already exists on Google (the Uberall listing will have the claim status CLAIMED_BY_OTHERS), the splash page will offer both to connect the Google account managing that profile, or to request admin access to it:

The request admin rights link will redirect to the following dialogue from Google:

• Request with a regular GBP account:

• Request with a GBP account with access to an organization account: