How do I connect Convert to Google Apps?

This article will provide you the basis to develop a Google Apps Script that can connect to the Convert via its API.

Introduction: Convert Experiences provides a powerful API that allows you to retrieve data about your experiments and integrate it with other applications. This article will guide you through the process of creating a Google Apps Script that queries the Convert Experiences API using its own endpoints. By following these steps, you'll be able to build custom dashboards and automate reporting tasks using Convert experiment data.

Prerequisites: Before getting started, ensure you have the following:

1. A Convert Experiences account with an active project.
2. Access to the Convert Experiences API and the necessary credentials (API Key and API Secret).
3. Basic knowledge of JavaScript and Google Apps Script.

Step 1: Set up the Script

1. Open Google Drive and create a new Google Apps Script project.
2. In the script editor, create a new file named "main.gs".
3. Copy and paste the following code into the "main.gs" file:

// main.gs
const apiKey = 'YOUR_API_KEY';
const apiSecret = 'YOUR_API_SECRET';
const accountId = YOUR_ACCOUNT_ID;
const projectId = YOUR_PROJECT_ID;
const experimentId = YOUR_EXPERIMENT_ID;

const apiUrl = `https://api.convert.com/api/v2/accounts/${accountId}/projects/${projectId}/experiences/${experimentId}?include[]=variations`;

function createSignature(requestBody = '') {
    const expiresTimestamp = Math.floor(Date.now() / 1000) + 300;
    const signString = `${apiKey}\n${expiresTimestamp}\n${apiUrl}\n${JSON.stringify(requestBody)}`;
    Logger.log('Sign String: ' + signString);
    const signature = Utilities.computeHmacSha256Signature(signString, apiSecret)
        .map((byte) => ("0" + (byte & 0xff).toString(16)).slice(-2))
        .join("");
    Logger.log('Signature: ' + signature);
    return { signature, expiresTimestamp };
}

function run() {
    try {
        Logger.log('Starting script execution.');

        const expiresTimestamp = Math.floor(Date.now() / 1000) + 300;
        const signString = `${apiKey}\n${expiresTimestamp}\n${apiUrl}\n`;
        Logger.log('Sign String: ' + signString);
        const signature = Utilities.computeHmacSha256Signature(signString, apiSecret)
            .map((byte) => ("0" + (byte & 0xff).toString(16)).slice(-2))
            .join("");
        Logger.log('Signature: ' + signature);

        const headers = {
            'Convert-Application-ID': apiKey,
            'Authorization': `Convert-HMAC-SHA256 Signature=${signature}`,
            'Expires': `${expiresTimestamp}`,
            'Content-Type': 'application/json'
        };
        const options = {
            method: 'get',
            headers: headers,
            muteHttpExceptions: true
        };

        Logger.log('Making API request to: ' + apiUrl);
        const response = UrlFetchApp.fetch(apiUrl, options);
        Logger.log('API request completed.');

        const responseCode = response.getResponseCode();
        const responseBody = response.getContentText();
        const responseHeaders = response.getAllHeaders();

        Logger.log('Response Code: ' + responseCode);
        Logger.log('Response Headers: ' + JSON.stringify(responseHeaders, null, 2)); 
        Logger.log('Response Body: ' + responseBody);
    } catch (error) {
        Logger.log('Error making API request: ' + error.message);
        Logger.log('Error stack trace: ' + error.stack);  
    } finally {
        Logger.log('Script execution completed.');
    }
}

1. Replace 'YOUR_API_KEY', 'YOUR_API_SECRET', YOUR_ACCOUNT_ID, YOUR_PROJECT_ID, and YOUR_EXPERIMENT_ID with your actual Convert Experiences API credentials and IDs.

Step 2: Implement the API Request

1. The createSignature function generates the required signature for authentication using the HMAC-SHA256 algorithm. It takes the request body as an optional parameter.
2. The run function is the main entry point of the script. It constructs the API request, including the necessary headers and signature, and sends the request using the UrlFetchApp.fetch method.
3. The response from the Convert Experiences API is logged, including the response code, headers, and body.

Step 3: Run the Script

1. Save the script and run the run function from the script editor.
2. Check the logs in the script editor to view the API response and any potential errors.

Step 4: Process the API Response

1. Parse the JSON response from the API to extract the relevant data.
2. Use the extracted data to populate your custom dashboard or perform further analysis.

Example:

const responseData = JSON.parse(responseBody);
const experimentName = responseData.name;
const variations = responseData.variations;
// Process the experiment data as needed

Step 5: Schedule the Script (Optional)

1. If you want to automate the data retrieval process, you can set up a trigger to run the script at regular intervals.
2. In the script editor, go to "Edit" > "Current project's triggers".
3. Click on "Add Trigger" and configure the desired frequency and parameters for running the script.

Conclusion: By following these steps, you can create a Google Apps Script that queries the Convert Experiences API to retrieve experiment data. This script serves as a foundation for building custom dashboards and automating reporting tasks. Feel free to expand upon this script to suit your specific requirements and integrate Convert data into your workflow seamlessly.

Remember to handle errors gracefully and ensure the security of your API credentials. Happy experimenting and data analysis!