Generating a Theme Modification URL

This document will explain how to generate an API token and use the API to generate a theme modification URL and also some useful patterns for using the URL.

To see an example of a theme modification URL in action click the 'Try It Out' button on the Blueberry landing page (opens in a new tab).

Overview

A theme modification URL is a URL that when visited appends a #GUID to the passed URL and redirects the visitor back to the location where they can view their theme as it is edited. The guid is used to look up a token that ensures the user has access to the page.

Creating An API token

You can create an API token by logging in and visiting the account settings tab. On the account settings tab, you will see a button "Generate token". This will allow you to name and create a token to access the API.

Authenticating

To make a request to the public API a client must include the X-Auth-Token header. The value of this header should be the token generated above.

Accessing the API

Currently, there is only one API - the API that allows you to generate a URL. To create a theme modification URL you make a post request with some JSON data. The requests and responses have the following formats:

POST /public_api/theme_modification_urls

Request Structure:

{
    "project_guid": String,
    "lookup_value": String,
    "redirect_url": String,
    "saveable": Boolean
}

project_guid (required)

Identifier of a project, as found on the projects tab (opens in a new tab).

lookup_value (required)

Either a valid URL in the case of the path in the case of a domain-based or path-based theme lookup strategy or any identifier in the case of a segment based. theme lookup strategy

redirect_url (required)

The location to redirect to after authorizing the browser. In most cases, this would be the location where the theming would take place.

saveable (optional) - defaults true

This option indicates whether or not you want the user to be able to persist changes. This option is useful if you paywall theming, you can let the customer go through the theming experience without actually being able to save the changes made.

Response Structure:

{
    "url": String,
    "success": Boolean,
    "errors": Array<String>
}

URL

This is the theme modification URL navigating to this URL will allow users to manipulate and persist changes to the theme.

success

Boolean value representing indicating whether or not the request succeeded.

errors

An array of error strings, each string representing an error or problem with the request.

CURL Example

curl \
    -X POST "https://api.getblueberry.io/public_api/theme_modification_urls" \
    --header "X-Auth-Token: AUTH_TOKEN" \
    --header "Content-Type: application/json" \
    --data $'{ 
    "project_guid": "PROJECT_GUID",
    "lookup_value": "LOOKUP_VALUE",
    "redirect_url": "REDIRECT_URL" }'

Redirect Chain Pattern

How you choose to use a theme modification URL is up to you but the most common pattern is using a redirect chain. First, generate a theme modification URL then redirect to that URL. In Javascript pseudo-code that pattern would look like this:

app.get('/change-theme', (req, res) => {
    let user = doAuthorization(req);
    if (user) {
        // This assumes you have wrapped the API in the helper method you wrote called 'createmodificationURl'
        // that will generate a modification URL with the key of user id.
        let modificationUrlResponse = blueBerryApi.createModificationURl({
            project_guid: process.env.BLUEBERRY_PROJECT_GUID
            lookup_value: `https://my-site.com/profiles/${user.id}`
            redirect_url: `https://my-site.com/profiles/${user.id}`
        });
        if (modificationUrlResponse["success"]) {
            res.redirect(modificationUrlResponse['url'])
        }
    }   
}

Redirect chain Steps

Integrating App Steps

1. A user visits the /change-theme endpoint.
2. The user is then authenticated with whatever existing auth mechanism is in place.
3. Given an authenticated user we generate a modification URL.
4. Check to make sure the API request succeeded.
5. Redirect to the newly generated Blueberry modification URL.

Automatic Blueberry Steps

6. Blueberry receives the request
7. Blueberry redirects the user back to your application per the redirect_url parameter with an added guid.
8. The user is now able to edit their theme in real time and observe the changes they are making!

Server Side HTML Pattern

Alternatively, you can include the modification URL directly into HTML you generate on the server side. Here is an example using a Ruby on Rails pseudocode:

def show_settings_page   
    theme_modification_url_response = Blueberry.create_modification_url(
        project_guid: process.env.BLUEBERRY_PROJECT_GUID
        lookup_value: `https://my-site.com/profiles/#{user.id}`
        redirect_url: "https://my-site.com/profiles/#{@current_user.id}"
    )
        
    if theme_modification_url_response["success"]
        @theme_modification_url = theme_modification_url_response["url"]
        render :template => "users/settings"
    end
end

this Rails action corresponds to this HTML template:

<!-- users/settings.html.erb -->
<div>
    Settings for <%= @current_user.name %> 
    <a href="<%= @theme_modification_url %>">Modify theme</a>
<div>
 

Integrating App Steps

1. A user visits the /settings endpoint.
2. The user is then authenticated with whatever existing auth mechanism is in place and the @current_user variable is set.
3. Given an authenticated user we generate a modification URL.
4. Check to make sure the API request succeeded.
5. We render the HTML with the theme modification URL built into the page.

Assuming the user clicks on the link the next steps would be:

Automatic Blueberry Steps

6. Blueberry receives the request
7. Blueberry redirects the user back to your application per the redirect_url parameter with an added guid.
8. The user is now able to edit their theme in real time and observe the changes they are making!