Restoring a website when EC2 fails

Recently, one of my websites went down. After noticing, I checked my EC2 dashboard and saw the instance stopped. AWS had emailed me to say that due to a physical hardware issue, it was terminated. When an instance is terminated, all of its data is lost. Luckily, all of my data is backed up automatically every night.

Since I don’t use RDS, I have to manually manage data redundancy. After a few disasters, I came up with a solution to handle it. I trigger a nightly cron-job to run a shell script. That script takes a MySQL dump and uploads it to S3.

As long as I have the user generated data, everything else is replaceable.  The website that went down is a fitness tracking app. Every day users record their martial arts progress. Below are the ten steps taken to bring everything back up.

  1. Launch a new EC2 instance
  2. Configure the security group for that instance –  I can just use the existing one
  3. Install Apache and MariaDB
  4. Secure the database
  5. Install PhpMyAdmin – I use this tool to import the .sql file in the next step
  6. Import the database backup – I downloaded the nightly .sql file dump from my S3 repo
  7. Setup automatic backups, again
  8. Install WordPress and restore the site’s blog
  9. Configure Route 53 (domain name) and SSL (https) – make the website live again
  10. Quality Assurance – “smoke test” everything to make sure it all looks correct

Use this as a checklist to make sure you don’t forget any steps. Read through the blog posts that I hyperlinked to get more details.

Shopify App with Theme App Extensions

After writing my last post about How to create a Shopify app, I decided to build a new one as a side project. Taking myself through the entire process helped me to tighten up the details I mentioned. This one adds a sticky banner to a store’s front-end, prompting users to “click to call”.

A sticky banner on a website

It’s built on top of the code I used for the SplitWit Shopify app. I adjusted some of the methods to accept configuration parameters to differentiate between the two. Code had to be added to support new functionality. SplitWit already had a feature to add a sticky banner to a site’s existing UI. I used the same workflow to inject the merchant’s settings as JavaScript.

function writeSnippetFile($shopify_installation_complete_id){
    
    $conn = $this->connection;
    $sql = "SELECT * FROM `prompts` WHERE shopify_installation_complete_id = ?"; 
    $result = $conn->prepare($sql); 
    $result->execute(array($shopify_installation_complete_id));
    $row = $result->fetch(PDO::FETCH_ASSOC);
    $phone_number = $row['phone_number'];
    $message_text = $row['message_text'];
    $color = $row['color'];
    $bg_color = $row['bg_color'];
    $position = $row['position'];
    $display = $row['display'];
    $mobile_only = $row['mobile_only'];
    $filename = $row['snippet'];
    
    $sticky_html = "";

    if($display == "hide"){
        $sticky_html .= "<style>#ctc-splitwit-sticky{display:none;}</style>";
    }

    if($mobile_only == "true"){
        $sticky_html .= "<style>@media(min-width: 1000px){#ctc-splitwit-sticky{display:none;}}</style>";
    }

    $sticky_html .= "<div style='font-weight:bold;".$position.":0;position:fixed;z-index:100000;left:0px;text-align:center;padding:8px 20px;width:100%;background:".$bg_color.";color:".$color."' id='ctc-splitwit-sticky'><p style='margin:0px'><a href='tel:".$phone_number."'>".$message_text."</a></p></div>";

    $changecode = '$("body").append("'.$sticky_html.'")';

    $snippet_template = file_get_contents("/var/www/html/click-to-call/snippet/snippet-template.js");
    $myfile = fopen("/var/www/html/click-to-call/snippet/".$filename, "w") or die("Unable to open file!");

    $txt = "window.CTCsplitWitChangeCode = ".$changecode . "\n" . $snippet_template;

    fwrite($myfile, $txt) or die("Unable to save file!");

    fclose($myfile);
}

The app’s admin view is a simple input form with settings to control the sticky bar UI that is injected into the merchant’s store-front.

admin view with a settings input form

In addition to updating and refactoring my code, I wrote copy and drafted design for this digital product. I used SplitWit branding guidelines (fonts, colors, etc.) to establish an adjacent feel.

Although it’s optional, I wanted to include a promo video in the listing. Having had previously created videos for SplitWit, I was able to quickly spin one together. I already created background music files in Garage Band for other projects. Here’s the one I chose to use – feel free to borrow it for what ever you like. The text animations were exported from Keynote. I added screenshots, included stock animation from VideoPlasty, and recorded voice-over lines using a Yeti microphone.

splitwit youtube video

I drafted other graphic assets that were required in the app listing using the GIMP – software I’ve used for over twenty years

app listing key benefits

A few days after submission, I received an email with required changes.

They were mostly minor issues. Things like the app’s name, a screenshot used in the listing, and an OAuth redirect bug.

One of the requests said, “Update your app to theme app extensions to ensure compatibility with Online Store 2.0 themes.”

2.0 themes? What does that mean?

Shopify recently announced Online Store 2.0 (OS 2.0). It’s essentially a set of improvements to the platform that makes themes and apps more flexible and maintainable. This benefits both merchants and developers. Enhanced app support means app functionality can be leveraged anywhere in a theme by using app blocks in the theme customizer.

SplitWit Click-to-Call injects HTML to manipulate a store’s user interface. That code comes from a JavaScript file that’s referenced in the page’s source code. That reference is added upon installation using the ScriptTag API. The JS file itself is generated & updated whenever a merchant clicks “save” in the app’s admin view. This required change is requesting that we provide an app block option as an alternative for compatible themes.

Shopify is encouraging OS 2.0 apps to instead use “theme app extensions” because they don’t edit theme code. It allows merchants to add your app’s UI elements, along with any settings, through its theme editor.

Shopify's theme editor

The documentation mentions that it “reduce[s] the effort required to integrate apps in themes”. In my particular case, it actually seems to add a step.

Theme App Extensions

App blocks are a type of “theme app extension” supported by Shopify’s Online Store 2.0. To create an app block available in the theme editor, I added a directory to my app using the below file structure. I was able to auto-generate it with the Shopify CLI by using the command shopify extension create.

app extension file structure

From the command line, I registered this folder as an extension, and pushed my code.

command line updates

In my app block .liquid file I used the same HTML template from my original PHP snippet, swapping my database variables for Shopify block settings.

{% if block.settings.display == "hide" %}
<style>#ctc-splitwit-sticky{display:none;}</style>
{% endif %} 

{% if block.settings.mobile_only == "yes" %}
<style>@media(min-width: 1000px){#ctc-splitwit-sticky{display:none;}}</style>
{% endif %} 

<div style="font-weight:bold;{{block.settings.position}}:0;position:fixed;z-index:100000;left:0px;text-align:center;padding:8px;width:100%;background:{{block.settings.bg_color}};color:{{block.settings.color}}" id="ctc-splitwit-sticky"><p style=margin:0px><a style="color:{{block.settings.color}} " href="tel:{{block.settings.phone_number}}">{{block.settings.message_text}}</a></p></div>

{% schema %}
{
  "name": "Click To Call",
  "target": "section",
  "settings": [
    {
      "type": "color",
      "id": "bg_color",
      "label": "Banner color",
      "default": "#0000FF"
    },
    {
      "type": "color",
      "id": "color",
      "label": "Text color",
      "default": "#FFFFFF"
    },
    {
      "type": "text",
      "id": "message_text",
      "label": "Message text",
      "default": "Call us now!"
    },
    {
      "type": "text",
      "id": "phone_number",
      "label": "Phone number",
      "default": "(212)-555-5555"
    },
    {
      "type": "radio",
      "id": "position",
      "label": "Position",
      "options": [
        {
          "value": "top",
          "label": "Top"
        },
        {
          "value": "bottom",
          "label": "Bottom"
        }
      ],
      "default": "top"
    },
    {
      "type": "radio",
      "id": "display",
      "label": "Display",
      "options": [
        {
          "value": "hide",
          "label": "Hide"
        },
        {
          "value": "show",
          "label": "Show"
        }
      ],
      "default": "show"
    },
    {
      "type": "radio",
      "id": "mobile_only",
      "label": "Mobile only",
      "options": [
        {
          "value": "yes",
          "label": "Yes"
        },
        {
          "value": "no",
          "label": "No"
        }
      ],
      "default": "no"
    }
  ]
}
{% endschema %}

The schema JSON explicates the settings inputs exposed to the merchant. I set them to match the original settings view from my app’s interface.

app block settings in the shopify theme editor

This approach lets Shopify maintain the app’s configurations, instead of my SplitWit server database that’s hosted on AWS EC2. That’s less data developers can capture, but also less of a hosting burden.

Any time you update the theme app extension you’ll need to re-push the code from the Shopify CLI with the command shopify extension push. The extension code is not hosted on your own server. It lives solely in the Shopify infrastructure ecosystem.

Verify theme support

Not all themes support theme app extensions. Theme support needs to be verified at the time of installation.

The original settings view is still needed, just in case the merchant’s published theme does not support app blocks. If app blocks are supported, I don’t install the script tag snippet at all. Instead, the settings view is replaced with integration instructions telling the merchant how to activate the sticky banner from the theme editor.

If app blocks are not supported by the active theme, the snippet is installed and the settings input form displayed. Determining if the merchant’s theme supports app blocks requires adding the read_themes Shopify API scope access to the oAuth request.

$scopes = "write_script_tags,read_themes";
$redirect_url = "https://".$shop."/admin/oauth/authorize?client_id=". $this->api_key ."&scope=".$scopes."&redirect_uri=". $redirect_uri ."&state=".$nonce . "&grant_options[]=per-user";

I tested my code by switching from the basic “Minimalist” theme to a OS2.0 theme called “Dawn”. When the app is being installed, I do a few things to check if app blocks are supported:

  1. Get a list of the merchant’s installed themes, and check which is currently published
  2. Retrieve a list of assets in the published theme
  3. Check if JSON template files exist for at least one of the desired templates
$params = [];
$json_string_params = json_encode($params);
$headers = array(
'X-Shopify-Access-Token:' . $access_token,
'content-type: application/json'
);

// $install_ctc_curl_response_json = $this->curlApiUrl("https://www.splitwit.com/service-layer/click-to-call-service.php?method=installShopifyApp&installation_complete_id=".$installation_complete_id, $params);

// check if this merchant's published theme supports app blocks
// https://shopify.dev/api/admin-rest/2021-10/resources/theme
$read_themes_url = "https://" . $this->api_key . ":" . $this->secret . "@" . $shop . "/admin/api/2021-10/themes.json"; // list of all installed themes
$read_themes_curl_response_json = $this->curlApiUrl($read_themes_url, $json_string_params, $headers, false);
$themes = $read_themes_curl_response_json['themes'];
$published_theme_id = 0;
foreach ($themes as $theme) {
	// live theme has a role of main
	if($theme['role'] == "main"){
		$published_theme_id = $theme['id'];
		// echo "The main theme is " . $theme['name'] . "<br /><br /><br />";
	}
}

// Retrieve a list of assets in the published theme
$get_theme_assets_url = "https://" . $this->api_key . ":" . $this->secret . "@" . $shop . "/admin/api/2021-10/themes/".$published_theme_id."/assets.json"; 
$get_theme_assets_curl_response_json = $this->curlApiUrl($get_theme_assets_url, $json_string_params, $headers, false);


// Check if JSON template files exist for at least one of the desired templates
// For other applications, you might want to check that they exist for ALL desired templates
$assets = $get_theme_assets_curl_response_json['assets'];
$probably_block_support = false;
$templates = ['index', 'cart', 'page.contact', 'product', 'collection'];

foreach ($assets as $asset) { 						
	foreach ($templates as $template) {
		if($asset['key'] == "templates/".$template.".json" ){
			$probably_block_support = true;
			break; // this checks that JSON template files exist for at least one of the desired templates. If you want to check that they exist for ALL desired templates, you can move this break to the 'else' condition
		}else{
			$probably_block_support = false;
			// break; 
		}
	}

	if($probably_block_support){
		break;
	}
}

Shopify recommends additionally checking:

  1. The body of JSON templates to determine what section is set as `main`
  2. The content of each `main` section and if it has a schema that contains a block of type ‘@app’

 

<?php
// we can continue further checks here
// https://shopify.dev/apps/online-store/verify-support
 					
if($probably_block_support){
	// https://shopify.dev/api/admin-rest/2021-10/resources/asset#[get]/admin/api/2021-10/themes/{theme_id}/assets.json?asset[key]=templates/index.liquid

	foreach ($templates as $template) {
		$get_single_asset_url = "https://" . $this->api_key . ":" . $this->secret . "@" . $shop . "/admin/api/2021-10/themes/".$published_theme_id."/assets.json?asset[key]=templates/".$template.".json"; 
	
		$get_single_asset_curl_response_json = $this->curlApiUrl($get_single_asset_url, $json_string_params, $headers, false);
		// var_dump($get_single_asset_curl_response_json['asset']['value']);
		$asset_value_json = json_decode($get_single_asset_curl_response_json['asset']['value']);
		var_dump($asset_value_json->sections);
		echo "<hr />";
		// break;
	}
}

From my testing, those last two steps were not reliable and ultimately irrelevant.

If app blocks are supported, the snippet is not created nor injected through the Shopify script_tag API. I make note of it in the database.

$timestamp = time(); 
$snippet = md5($timestamp);
$snippet = $snippet . ".js";
$using_app_blocks = 0;

// don't create the snippet if we think they have app block support
if ($probably_block_support) {
  $using_app_blocks = 1;

}else{

  // create snippet file
  $myfile = fopen("/var/www/html/click-to-call/snippet/".$snippet, "w");
  fclose($myfile);

  // inject JS snippet into site
  // https://shopify.dev/docs/admin-api/rest/reference/online-store/scripttag#create-2020-04
  $create_script_tag_url = "https://" . $this->api_key . ":" . $this->secret . "@" . $shop . "/admin/api/2020-04/script_tags.json";
  $params = [
       'script_tag' => [
         'event' => 'onload',
         'src' => 'https://www.splitwit.com/click-to-call/snippet/' . $snippet
       ]
  ];
  $json_string_params = json_encode($params);
  $create_script_curl_response_json = $this->curlApiUrl($create_script_tag_url, $json_string_params, $headers);
}

$stmt = $conn->prepare("INSERT INTO `prompts` (shopify_installation_complete_id, snippet, shop, using_app_blocks, access_token) VALUES (:shopify_installation_complete_id, :snippet, :shop, :using_app_blocks, :access_token)");	
$stmt->bindParam(':shopify_installation_complete_id', $installation_complete_id);
$stmt->bindParam(':snippet', $snippet);					
$stmt->bindParam(':shop', $shop);					
$stmt->bindParam(':using_app_blocks', $using_app_blocks);					
$stmt->bindParam(':access_token', $access_token);					
$stmt->execute();

I check for that value from the front-end to display steps for integrating the app block from the theme customizer. Shopify guidelines require that we provide merchants with post-installation onboarding instructions. Those directions replace the settings input form. Configurations will be managed through the block itself.

Although Shopify does provide recommendations for merchant onboarding, there is no boiler-plate copy. A basic explanation, with screenshots, sufficed.

onboarding instructions

These updates satisfied the app review team’s request. I responded to their email, and a day later received their reply. It complained that the “app doesn’t have a functional user interface (UI)” when app blocks are enabled. That was because all of the settings were being managed by the app block data. To solve this issue, I moved the phone number and message fields back to the app’s settings view. I saved those values as metafields using the Shopify REST API.

// write this data to custom metafields, so we can access it from app blocks
$clickToCallRecord = $this->getClickToCallRecord($shopify_installation_complete_id);			
$access_token = $clickToCallRecord['access_token'];
$shop = $clickToCallRecord['shop'];
$params = [];
$params = [
    "metafield" => [
      "namespace" => "clicktocall",
      "key" => "phone_number",
      "value" => $_POST['phone_number'],
      "type" => "string"
    ],
    "metafield" => [
      "namespace" => "clicktocall",
      "key" => "message_text",
      "value" => $_POST['message_text'],
      "type" => "string"
    ],
  ];
$json_string_params = json_encode($params);
$headers = array(
  'X-Shopify-Access-Token:' . $access_token,
  'content-type: application/json'
);
 

$url = "https://" . $this->api_key . ":" . $this->secret . "@" . $shop . "/admin/api/2021-10/metafields.json";
$response = $this->curlApiUrl($url, $json_string_params, $headers);

Update: The Shopify metafield POST API would only create/update a single metafield per request. I had to break it out into two calls. From what I’ve read it seems like a PUT request might do that trick for multiple fields, but for my use-case this approach is fine. Here you can see how I do it when setting default metadata on installation:

$params = [
    "metafield" => [
      "namespace" => "clicktocall",
      "key" => "phone_number",
      "value" => "(555)-555-5555",
      "type" => "string"
    ]
  ];
$json_string_params = json_encode($params);


$url = "https://" . $this->api_key . ":" . $this->secret . "@" . $shop . "/admin/api/2021-10/metafields.json";
$response = $this->curlApiUrl($url, $json_string_params, $headers);

$params = [
    "metafield" => [
      "namespace" => "clicktocall",
      "key" => "message_text",
      "value" => "Give us a call!",
      "type" => "string"
    ],
  ];
$json_string_params = json_encode($params);
$response = $this->curlApiUrl($url, $json_string_params, $headers);

 

I populated them from the app block liquid file by accessing the global ‘shop’ object:

<a style="color:{{block.settings.color}} " href="tel:{{ shop.metafields.clicktocall.phone_number.value }}">{{ shop.metafields.clicktocall.message_text.value }}</a>

After another response, they commented that I should be using “App Embed Blocks” instead of just “App Blocks”. That was because my UI component is a “floating or overlaid element”. It exists outside of the normal DOM flow and was not inline with other HTML nodes. This only required a small update to the liquid file’s schema, changing the “target” from “section” to “body”.

Although only a small difference, it does affect how merchants add Click To Call in the theme customizer. They must navigate to the Theme Settings area, and add it as an “App Embed”.

adding an app embed block from the shopify theme editor

Luckily, I’m able to deep link merchants directly to that view from my onboarding instructions. The link also automatically activates my app embed. All I needed to do was get the extension’s UUID by running shopify extension info from my command line and I was able to build the URL.

Add the Click To Call App Block from <a href="https://<?php echo $clickToCallRecord['shop']; ?>/admin/themes/current/editor?context=apps&activateAppId=b52ccd8e-54b1-4b6d-a76f-abaed45dea97/click-to-call" target="_blank">the theme editor</a>

I updated my app’s home screen onboarding instructions to reflect this new flow. Everything appeared to be working when I tested, yet the app review team complained that the above issues were still unresolved. It turns out, I was able to immediately see changes to the extension that I pushed from the CLI because “development store preview” was enabled. The review team could not until I published a new version:

After that fix, the app was accepted to the Shopify App Market. If you are a Shopify merchant, check it out and let me know what you think.

cURL PHP Abstraction

cURL is a PHP library that lets you make HTTP requests. To use it, you need to install the libcurl package. If you’re using PHP on web server, it’s probably already there. The cURL functions have a number of options, depending on what request you’d like to make. You can read all about it in the PHP official documentation.

I had a number of projects that was using it all over the place, to make a variety of requests. I was repeating a lot of code, and my mix-matching began to get confusing. Finally, I wrote a function that takes request options as arguments and does all the work:

public function curlApiUrl($url, $params, $headers = false, $http_verb = false){
	
	$curl_connection = curl_init();
	// curl_setopt($curl_connection, CURLOPT_FOLLOWLOCATION, true);
	if($headers){
		curl_setopt($curl_connection, CURLOPT_HTTPHEADER, $headers);
		curl_setopt($curl_connection, CURLOPT_HEADER, false);
	}
	curl_setopt($curl_connection, CURLOPT_URL, $url);

	if($http_verb == "post"){
		curl_setopt($curl_connection, CURLOPT_POST, true);
		curl_setopt($curl_connection, CURLOPT_POSTFIELDS, $params);
	}
	if($http_verb == "delete"){
		curl_setopt($curl_connection, CURLOPT_CUSTOMREQUEST, "DELETE");
	}
	if($http_verb == "put"){
	    curl_setopt($curl_connection, CURLOPT_CUSTOMREQUEST, "PUT");
		curl_setopt($curl_connection, CURLOPT_POSTFIELDS, $params);
	}
	//end TODO
	curl_setopt($curl_connection, CURLOPT_RETURNTRANSFER, true);
	$curl_response = curl_exec($curl_connection);
	$curl_response_json = json_decode($curl_response,true);
	curl_close($curl_connection);
	return $curl_response_json;
}

I used this as a class method in the back-end services to create Shopify apps. It’s implementation looks like this:

$create_recurring_charge_url = "https://" . $this->api_key . ":" . $this->secret . "@" . $shop . "/admin/api/2020-04/recurring_application_charges.json";
$params = [
    'recurring_application_charge' => [
        'name' => 'Basic Plan',
        'price' => 25.0,
        // 'return_url' => "https://" . $shop . "/admin/apps/splitwit",
        // 'test' => true,
        'return_url' => "https://www.splitwit.com/service-layer/shopify-app-service?method=confirmSubscription"
    ]
];
$headers = array(
	'X-Shopify-Access-Token: ' . $access_token,
 	'content-type: application/json'
);
$json_string_params = json_encode($params);

curlApiUrl($create_recurring_charge_url, $json_string_params, $headers);

cURL’s default request type is always GET. If I want to use a different HTTP verb, I can specify it as an argument. Adding this function as an abstraction layer over existing methods helps me get things done more quickly, and kept my code clear, clean, and under control.

Radio button value checked from a database in PHP

Form input with PHP

When building software user interfaces, I create HTML forms to manage any app settings. I’ll usually have a few text and radio inputs like this:

Using PHP, I grab a database record and access its properties to populate the form. Filling out the text inputs is straight-forward:

<?php $clickToCallRecord = $db_service->getClickToCallRecord($installation_complete_id); ?>

<div class="form-group">
    <label>Phone number:</label>
    <input class="form-control" type="tel" name="phone_number" value="<?php echo $clickToCallRecord['phone_number']; ?>" placeholder="(123)-456-7890">
</div>
<div class="form-group">
    <label>Message:</label>
    <input class="form-control" type="text" name="message_text" value="<?php echo $clickToCallRecord['message_text']; ?>" placeholder="Call Us Now">
</div>
<div class="form-group">
    <label>Background Color:</label>
    <input class="form-control" type="text" value="<?php echo $clickToCallRecord['bg_color']; ?>" name="bg_color">
</div>

Checking the correct radio input requires our code to evaluate the data value. I add a PHP variable to each of the inputs as attributes. Those variables will render to either “checked” or blank:

<?php
    $top_checked = "";
    $bottom_checked = "";
    $position = $clickToCallRecord['position'];
    if($position == "top"){
        $top_checked = "checked";
        $bottom_checked = "";
    }else{
        $top_checked = "";
        $bottom_checked = "checked";
    }

    $show_checked = "";
    $hide_checked = "";
    $display = $clickToCallRecord['display'];
    if($display == "show"){
        $show_checked = "checked";
        $hide_checked = "";
    }else{
        $show_checked = "";
        $hide_checked = "checked";
    }

?>

<div class="form-group">
    <label>Position:</label>
    <div>
        <div class="form-check form-check-inline">
          <input <?php echo $top_checked; ?> class="form-check-input" type="radio" name="position" value="top">
          <label class="form-check-label" for="matchtype">Top</label>
        </div>
        <div class="form-check form-check-inline">
          <input <?php echo $bottom_checked; ?> class="form-check-input" type="radio" name="position"  value="bottom">
          <label class="form-check-label" for="matchtype">Bottom</label>
        </div>
    </div>
</div>
<hr />
<div class="form-group">
    <label>Display:</label>
    <div>
        <div class="form-check form-check-inline">
          <input <?php echo $show_checked; ?> class="form-check-input" type="radio" name="display" value="show">
          <label class="form-check-label" for="matchtype">Show</label>
        </div>
        <div class="form-check form-check-inline">
          <input <?php echo $hide_checked; ?> class="form-check-input" type="radio" name="display"  value="hide">
          <label class="form-check-label" for="matchtype">Hide</label>
        </div>
    </div>
</div>

This example comes from a Shopify app that helps stores increase conversions by adding a UI element prompting customers to call a phone number.

How to create a Shopify app with PHP

Build a Shopify App with PHP

Developing a marketplace app for your SAAS will grow organic traffic and lets users find you. Potential customers can discover your digital product where they are already looking. Software services that occupy the eCommerce space have a chance to help Shopify store owners grow their businesses. Creating a public Shopify app benefits both developers and the merchant user-base in the Shopify App Store ecosystem.

Recently, Shopify announced that it is decreasing the share of profit that it takes from developers. Each year, developers keep all of their revenue up to the first one-million dollars.

Why Build a Marketplace App?

The short answer: Discoverability.

A few years ago, I built a fitness tracking app for a niche sport. It was a hobby project to better track my BJJ training.  Since then, I continue to average ~10 registrations weekly without any marketing efforts.

Consistent BJJ Tracker sign-ups are driven from Google Play. Even though it is only a web app (PWA), I was able to bundle it into an APK file using Trusted Web Activities and Digital Asset Links. Having an app listed in a marketplace leads to new users finding it naturally.

My next side project was a SAAS for split testing & conversion optimization. It helps websites A/B test to figure out what front-end changes lead to more sales, sign-ups, etc. The Shopify App Store was as perfect fit to attract shop owners to use SplitWit. I decided to build a public, embedded, Shopify app to reach new prospects.

I’ll explain how I did it, along with examples of building another one, all using PHP. This guide will make launching a Shopify App Store app easy, fast, repeatable.

SplitWit on Shopify

Creating a Public Shopify App with PHP

Embedded Shopify apps display in a merchant’s admin dashboard. They are meant to “add functionality to Shopify stores“. They are hosted on the developer’s infrastructure and are loaded via iFrame within Shopify. You can create a new app in your Shopify Partners dashboard to get started.

create a shopify app

Since the SplitWit SAAS already existed as a subscription web app built on the LAMP stack, I only had to handle Shopify specific authorization and payments. I could essentially load the existing app in the dashboard’s iFrame after authentication. The new code I wrote contains methods for checking installation status, building the oAuth URL, subscribing users to recurring application charges, and more.

When I created my next Shopify app, Click to Call, I leveraged that code and refactored it to be more reusable. Configurable parameters let me set the database and API credentials dynamically.

Step 1: Check Installation Status

When the app’s url loads in the merchant admin dashboard, the first step is to check installation status for that shop.

public function checkInstallationStatus(){
	$conn = $this->conn;
	$shop = $_GET['shop'];

	//check if app is already installed or not
	$statement = $conn->prepare("SELECT * FROM `shopify_installation_complete` WHERE shop = :shop");
	$statement->execute(['shop' => $shop]);
	$count = $statement->rowCount();
	if($count == 0){
		//app is not yet installed
		return false;
	}else{
		//app is already installed
		$row = $statement->fetch();
		return $row;
	}

}

You’ll notice we don’t hit any Shopify API for this. Instead, our own database is queried. We manually track if the app has already been installed in a MySql table.

shopify installation record in a mysql database table

Two database tables are used to manage the Shopify App installation:

CREATE TABLE IF NOT EXISTS `shopify_authorization_redirect` (
    `shopify_authorization_redirect_id` int NOT NULL AUTO_INCREMENT,
    `shop` varchar(200),
    `nonce` varchar(500),
    `scopes` varchar(500),
    created_date datetime DEFAULT CURRENT_TIMESTAMP,
    updated_date datetime ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (`shopify_authorization_redirect_id`)
);

 
CREATE TABLE IF NOT EXISTS `shopify_installation_complete` (
    `shopify_installation_complete_id` int NOT NULL AUTO_INCREMENT,
    `splitwit_account_id` int,
    `splitwit_project_id` int,
    `shop` varchar(200),
    `access_token` varchar(200),
    `scope` varchar(200),
    `expires_in` int,
    `associated_user_scope` varchar(200),
    `associated_user_id` BIGINT,
    `associated_user_first_name` varchar(200),
    `associated_user_last_name` varchar(200),
    `associated_user_email` varchar(200),
    `associated_user_email_verified` varchar(10),
    `associated_user_account_owner` varchar(10),
    `associated_user_account_locale` varchar(10),
    `associated_user_account_collaborator` varchar(10),
    created_date datetime DEFAULT CURRENT_TIMESTAMP,
    updated_date datetime ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (`shopify_installation_complete_id`)
);

The root file (index.php) looks like this:

<?php

require '/var/www/html/service-layer/shopify-app-service.php';
include 'shopify-creds.php'; // $api_key, $secret, $app_db, $app_slug
use SplitWit\ShopifyService\ShopifyService;
$shopify_service = new ShopifyService($api_key, $secret, $app_db);

$already_installed = $shopify_service->checkInstallationStatus();

if(!$already_installed){
    $install_redirect_url = $shopify_service->buildAuthorizationUrl(false, $app_slug);
}else{
    $install_redirect_url = $shopify_service->buildAuthorizationUrl(true, $app_slug);
}
header('Location: ' . $install_redirect_url );

?>

After determining the merchant’s installation status, the next step is to authenticate them.

oAuth Authentication

The Shopify developer resources explain “how to ask for permission” with oAuth. The merchant user needs to be redirected to a Shopify URL:

https://{shop}.myshopify.com/admin/oauth/authorize?client_id={api_key}&scope={scopes}&redirect_uri={redirect_uri}&state={nonce}&grant_options[]={access_mode}

I wrote a PHP class “ShopifyService” (shopify-app-service.php) to handle all of the Shopify specific logic. The method buildAuthorizationUrl() builds the Shopify authorization URL. It accepts a boolean parameter set according to the merchant’s installation status. That value toggles the authorization URL’s redirect URI, directing the code flow through either first-time installation or re-authentication.

The built URL includes query params: an API key, a nonce, the scope of permission being requested, and a redirect URI. The shop name is the subdomain, and can be pulled as GET data delivered to your app.

The API key can be found in the developer’s partner dashboard in the app’s overview page.

A nonce (“number used once”) is used as an oAuth state parameter. It serves to “link requests and callbacks to prevent cross-site request forgery attacks.” We save that random value in our database to check against during the oAuth callback.

The redirect URI (the oAuth callback) is dynamic based on the users installation status.

public function buildAuthorizationUrl($reauth = false, $slug= "shopify-app"){
	$conn = $this->conn;
	$requestData = $this->requestData;
	$scopes = "write_script_tags"; //write_orders,read_customers, read_content
	$nonce = bin2hex(random_bytes(10));
	$shop = $requestData['shop'];

	//first check if there is already a record for this shop. If there is, delete it first.
	$statement = $conn->prepare("SELECT * FROM `shopify_authorization_redirect` WHERE shop = :shop");
	$statement->execute(['shop' => $shop]);
	$count = $statement->rowCount();
	
	if($count > 0){
		$statement = $conn->prepare("DELETE FROM `shopify_authorization_redirect` WHERE shop = :shop");
		$statement->execute(['shop' => $shop]);
	}

	$statement = $conn->prepare("INSERT INTO `shopify_authorization_redirect` (shop, nonce, scopes) VALUES (:shop, :nonce, :scopes)");
	$statement->bindParam(':shop', $shop);
	$statement->bindParam(':nonce', $nonce);
	$statement->bindParam(':scopes', $scopes);
	$statement->execute();

	
	$redirect_uri = "https://www.splitwit.com/".$slug."/authorize-application";
	
	if($reauth){ //change the redirect URI
		$redirect_uri = "https://www.splitwit.com/".$slug."/reauthorize-application";
	}

	$redirect_url = "https://".$shop."/admin/oauth/authorize?client_id=". $this->api_key ."&scope=".$scopes."&redirect_uri=". $redirect_uri ."&state=".$nonce . "&grant_options[]=per-user";

	return $redirect_url;

}

Both possible redirect URLs needed to be white-listed in the “App setup” page.

white listed URLs

A location header routes the user. If the app hasn’t been installed yet, Shopify prompts the merchant to confirm authorization.

install shopify app

If the app was already installed then the oAuth grant screen is skipped entirely and the merchant is immediately routed to the /reauthorize-application resource instead (and ultimately lands on the app home screen).

Install App & Register the Merchant User

What actually happens when “Install app” is clicked?  The user is redirected from Shopify permissions screen back to our app ( /authorize-application ), calling the authorizeApplication() function. That method receives four values as GET parameters: ‘shop’, ‘state’, ‘hmac’, ‘code’

The ‘shop’ name is used to look up the nonce value we saved when the Shopify authorization URL was first built. We compare it to the ‘state’ parameter. This security step ensures that the callback request is valid and is not fraudulent. We also check that the shop name provided matches a valid Shopify hostname. Here is the relevant code, pulled from authorizeApplication():

$conn = $this->conn; 
$requestData = $this->requestData;
$requiredKeys = ['code', 'hmac', 'state', 'shop'];
foreach ($requiredKeys as $required) {
    if (!in_array($required, array_keys($requestData))) {
        throw new Exception("The provided request data is missing one of the following keys: " . implode(', ', $requiredKeys));
    }
}

//lookup and validate nonce
$shop = $requestData['shop'];

$statement = $conn->prepare("SELECT * FROM `shopify_authorization_redirect` WHERE shop = :shop");
$statement->execute(['shop' => $shop]);
$count = $statement->rowCount();
if($count == 0){
    throw new Exception("Nonce not found for this shop.");
}
$row = $statement->fetch();
$nonce = $row['nonce'];
//

//make sure the 'state' parameter provided matches the stored nonce
$state = $requestData['state'];
if($state !== $nonce){
    throw new Exception("Nonce does not match provided state.");
}
//

//validate the shop name
$pattern = "/[a-zA-Z0-9][a-zA-Z0-9\-]*\.myshopify\.com[\/]?/";
if(!preg_match($pattern, $shop)) {
    throw new Exception("The shop name is an invalid Shopify hostname.");
}

Every request or redirect from Shopify” includes a HMAC value that can be used to verify its authenticity. Here is how I do it in PHP:

public function verifyHmac($requestData){
	// verify HMAC signature. 
	// https://help.shopify.com/api/getting-started/authentication/oauth#verification
	if( !isset($requestData['hmac'])){
		return false;
	}

	$hmacSource = [];

	foreach ($requestData as $key => $value) {
	    
	    if ($key === 'hmac') { continue; }

	    // Replace the characters as specified by Shopify in the keys and values
	    $valuePatterns = [
	        '&' => '%26',
	        '%' => '%25',
	    ];
	    $keyPatterns = array_merge($valuePatterns, ['=' => '%3D']);
	    $key = str_replace(array_keys($keyPatterns), array_values($keyPatterns), $key);
	    $value = str_replace(array_keys($valuePatterns), array_values($valuePatterns), $value);

	    $hmacSource[] = $key . '=' . $value;
	}

	sort($hmacSource);
	$hmacBase = implode('&', $hmacSource);
	$hmacString = hash_hmac('sha256', $hmacBase, $this->secret);
	// Verify that the signatures match
    if ($hmacString !== $requestData['hmac']) {
        return false;
    }else{
    	return true;
    }
}

That method is called in the class construct function, to be sure it happens every time.

The ‘code’ parameter is the access code. It is exchanged for an access token by sending a request to the shop’s access_token endpoint. We record that token to the ‘shopify_installation_complete’ table along with relevant data.

To fully complete the installation, app specific project records are saved. For SplitWit, this means a user-account is created along with an initial project. Any JavaScript tags are injected onto the merchant’s site using the Shopify admin API ScriptTag resource. Linking a privately hosted JS file, unique to each merchant, allows our app to dynamically update the shop website. You can learn about how that snippet tag works in another post that explains how the visual editor is built.

Lastly, a webhook is created to listen for when this app in uninstalled ( ‘topic’ => ‘app/uninstalled’ ) in order to call our “uninstallApplication” method. Webhooks allow you to listen for certain events in a shop, and run code based on data about what happened.

Once installation is complete, our server returns a header that reloads the app.

shopify app

Below is the original authorizeApplication() method. Eventually, I moved app specific logic into its own files after refactoring this class to support another SAAS, Click to Call.

public function authorizeApplication(){
	$conn = $this->conn; 
	$requestData = $this->requestData;
	$requiredKeys = ['code', 'hmac', 'state', 'shop'];
        foreach ($requiredKeys as $required) {
           if (!in_array($required, array_keys($requestData))) {
             throw new Exception("The provided request data is missing one of the following keys: " . implode(', ', $requiredKeys));
           }
        }

	//lookup and validate nonce
	$shop = $requestData['shop'];
	
	$statement = $conn->prepare("SELECT * FROM `shopify_authorization_redirect` WHERE shop = :shop");
	$statement->execute(['shop' => $shop]);
	$count = $statement->rowCount();
	if($count == 0){
        throw new Exception("Nonce not found for this shop.");
	}
	$row = $statement->fetch();
	$nonce = $row['nonce'];
	//
	
	//make sure the 'state' parameter provided matches the stored nonce
	$state = $requestData['state'];
	if($state !== $nonce){
        throw new Exception("Nonce does not match provided state.");
	}
	//
	
	//validate the shop name
	$pattern = "/[a-zA-Z0-9][a-zA-Z0-9\-]*\.myshopify\.com[\/]?/";
	if(!preg_match($pattern, $shop)) {
        throw new Exception("The shop name is an invalid Shopify hostname.");
	}
	//

	$already_installed = $this->checkInstallationStatus();
	//if it is already installed, then lets update the access token 
        if(!$already_installed){
    	  //install the app
    	
	  //exchange the access code for an access token by sending a request to the shop’s access_token endpoint
	  $code = $requestData['code'];
	  $post_url = "https://" . $shop . "/admin/oauth/access_token";
		
	  $params = [
            'client_id'    => $this->api_key,
            'client_secret'    => $this->secret,
            'code'    => $code
          ];

          $curl_response_json = $this->curlApiUrl($post_url, $params);
	  $access_token = $curl_response_json['access_token'];
		
          $statement = $conn->prepare("INSERT INTO `shopify_installation_complete` (shop, access_token, scope, expires_in, associated_user_scope, associated_user_id, associated_user_first_name, associated_user_last_name, associated_user_email, associated_user_email_verified, associated_user_account_owner, associated_user_account_locale, associated_user_account_collaborator) VALUES (:shop, :access_token, :scope, :expires_in, :associated_user_scope, :associated_user_id, :associated_user_first_name, :associated_user_last_name, :associated_user_email, :associated_user_email_verified, :associated_user_account_owner, :associated_user_account_locale, :associated_user_account_collaborator)");
		
	  $statement->bindParam(':shop', $shop);
		
	  $statement->bindParam(':access_token', $access_token);
	  $statement->bindParam(':scope', $curl_response_json['scope']);
	  $statement->bindParam(':expires_in', $curl_response_json['expires_in']);
	  $statement->bindParam(':associated_user_scope', $curl_response_json['associated_user_scope']);
	  $statement->bindParam(':associated_user_id', $curl_response_json['associated_user']['id']);
	  $statement->bindParam(':associated_user_first_name', $curl_response_json['associated_user']['first_name']);
	  $statement->bindParam(':associated_user_last_name', $curl_response_json['associated_user']['last_name']);
	  $statement->bindParam(':associated_user_email', $curl_response_json['associated_user']['email']);
	  $statement->bindParam(':associated_user_email_verified', $curl_response_json['associated_user']['email_verified']);
	  $statement->bindParam(':associated_user_account_owner', $curl_response_json['associated_user']['account_owner']);
	  $statement->bindParam(':associated_user_account_locale', $curl_response_json['associated_user']['locale']);
	  $statement->bindParam(':associated_user_account_collaborator', $curl_response_json['associated_user']['collaborator']);

	  $statement->execute();
	  $installation_complete_id = $conn->lastInsertId();
		 
	  if(isset($curl_response_json['associated_user']['email']) && strlen($curl_response_json['associated_user']['email']) > 0){

		$store_name = explode(".", $shop);
		$store_name = ucfirst($store_name[0]);

		//create account
		$method = "thirdPartyAuth";
		$user_service_url = "https://www.splitwit.com/service-layer/user-service.php?third_party_source=shopify&method=" . $method . "&email=".$curl_response_json['associated_user']['email']."&companyname=" .$store_name . "&first=" . $curl_response_json['associated_user']['first_name'] . "&last=" . $curl_response_json['associated_user']['last_name'] ;
			
		$params = [];

		$curl_user_response_json = $this->curlApiUrl($user_service_url, $params);
		
		$account_id = $curl_user_response_json['userid']; 
			
		$method = "createProject";
			
		$project_service_url = "https://www.splitwit.com/service-layer/project-service.php?method=" . $method . "&accountid=" . $account_id;

		$params = [
	            'projectname'    => $store_name . " Shopify",
	            'projectdomain'    => "https://".$shop,
	            'projectdescription'    => ""
	        ];

		$curl_project_response_json = $this->curlApiUrl($project_service_url, $params);
		$project_id = $curl_project_response_json['projectid'];
		$snippet = $curl_project_response_json['snippet'];
			
			

		//inject JS snippet into site
		// https://shopify.dev/docs/admin-api/rest/reference/online-store/scripttag#create-2020-04
		$create_script_tag_url = "https://" . $this->api_key . ":" . $this->secret . "@" . $shop . "/admin/api/2020-04/script_tags.json";
		$params = [
                    'script_tag' => [
                     'event' => 'onload',
                     'src' => 'https://www.splitwit.com/snippet/' . $snippet
                    ]
        	];

        	$headers = array(
		  'X-Shopify-Access-Token:' . $access_token,
		  'content-type: application/json'
		);

		$json_string_params = json_encode($params);

		$create_script_curl_response_json = $this->curlApiUrl($create_script_tag_url, $json_string_params, $headers);
		
		//shopify app should only ever have access to this one project.
		//write accountID and ProjectID to this shopify_installation_complete record.

		$statement = $conn->prepare("UPDATE `shopify_installation_complete` SET splitwit_account_id = ?, splitwit_project_id = ? WHERE shopify_installation_complete_id = ?");

		$statement->execute(array($account_id, $project_id, $installation_complete_id));
			
    	}
		
    	//create webhook to listen for when app in uninstalled.
	//https://{username}:{password}@{shop}.myshopify.com/admin/api/{api-version}/{resource}.json
	// https://shopify.dev/docs/admin-api/rest/reference/events/webhook#create-2020-04
	$create_webhook_url = "https://" . $this->api_key . ":" . $this->secret . "@" . $shop . "/admin/api/2020-04/webhooks.json";
	$params = [
                'webhook' => [
                    'topic' => 'app/uninstalled',
                    'address' => 'https://www.splitwit.com/service-layer/shopify-app-service?method=uninstallApplication',
                    'format' => 'json'
                ]
        ];

	$headers = array(
		'X-Shopify-Access-Token:' . $access_token,
		'content-type: application/json'
	);
		
	$json_string_params = json_encode($params);

    	$create_webhook_curl_response_json = $this->curlApiUrl($create_webhook_url, $json_string_params, $headers);
		
	//installation complete.
   }

   header('Location: ' . "https://" . $shop . "/admin/apps/splitwit");
	
}

You’ll notice that I call a custom method that abstracts the PHP cURL (client URL library) methods. This helps me avoid repeating the same code in multiple places.

public function curlApiUrl($url, $params, $headers = false, $use_post = true, $use_delete = false, $use_put = false){
		
	$curl_connection = curl_init();
	// curl_setopt($curl_connection, CURLOPT_FOLLOWLOCATION, true);
	if($headers){
	    curl_setopt($curl_connection, CURLOPT_HTTPHEADER, $headers);
	    curl_setopt($curl_connection, CURLOPT_HEADER, false);
	}
	curl_setopt($curl_connection, CURLOPT_URL, $url);
    
       // TODO: refactor these three conditions into one, that accepts the RESTful request type!!
       if($use_post){
	    curl_setopt($curl_connection, CURLOPT_POST, true);
	    curl_setopt($curl_connection, CURLOPT_POSTFIELDS, $params);
	}
        if($use_delete){
	    curl_setopt($curl_connection, CURLOPT_CUSTOMREQUEST, "DELETE");
	}
        if($use_put){
	    curl_setopt($curl_connection, CURLOPT_CUSTOMREQUEST, "PUT");
	    curl_setopt($curl_connection, CURLOPT_POSTFIELDS, $params);
	}
	//end TODO

	curl_setopt($curl_connection, CURLOPT_RETURNTRANSFER, true);
	$curl_response = curl_exec($curl_connection);
	$curl_response_json = json_decode($curl_response,true);
	curl_close($curl_connection);
	return $curl_response_json;
}

The merchant will be able to find the app in the ‘Apps’ section of their dashboard. Shopify remembers that permission was granted by the merchant.

Returning User Log in

The oAuth grant screen will not show again when the app is selected in the future.  As the installation status returns true, our code will flow into the reAuthenticate() method. The same validation checks are performed and a new access token is received.

   
public function reAuthenticate(){
    $conn = $this->conn; 
    $requestData = $this->requestData;
    $requiredKeys = ['code', 'hmac', 'state', 'shop'];
    foreach ($requiredKeys as $required) {
        if (!in_array($required, array_keys($requestData))) {
            throw new Exception("The provided request data is missing one of the following keys: " . implode(', ', $requiredKeys));
            // return;
        }
    }

    //lookup and validate nonce
    $shop = $requestData['shop'];
    
    $statement = $conn->prepare("SELECT * FROM `shopify_authorization_redirect` WHERE shop = :shop");
    $statement->execute(['shop' => $shop]);
    $count = $statement->rowCount();
    if($count == 0){
        throw new Exception("Nonce not found for this shop.");
    }
    $row = $statement->fetch();
    $nonce = $row['nonce'];
    //
    
    //make sure the 'state' parameter provided matches the stored nonce
    $state = $requestData['state'];
    if($state !== $nonce){
        throw new Exception("Nonce does not match provided state.");
    }
    //
    
    //validate the shop name
    $pattern = "/[a-zA-Z0-9][a-zA-Z0-9\-]*\.myshopify\.com[\/]?/";
    if(!preg_match($pattern, $shop)) {
        throw new Exception("The shop name is an invalid Shopify hostname.");
    }

    //exchange the access code for an access token by sending a request to the shop’s access_token endpoint
    $code = $requestData['code'];
    $post_url = "https://" . $shop . "/admin/oauth/access_token";
    
    $params = [
        'client_id'    => $this->api_key,
        'client_secret'    => $this->secret,
        'code'    => $code
    ];

    $curl_response_json = $this->curlApiUrl($post_url, $params);
    $access_token = $curl_response_json['access_token'];
    
    $statement = $conn->prepare("UPDATE `shopify_installation_complete` SET access_token = ? WHERE shop = ?");
    $statement->execute(array($access_token, $shop));

    header('Location: ' . "/home?shop=".$shop);
}

The merchant is routed to the app’s /home location. A few session variables are set and the user interface is loaded.

<?php
require '/var/www/html/service-layer/shopify-app-service.php';
use SplitWit\ShopifyService\ShopifyService;
$shopify_service = new ShopifyService();
include '/var/www/html/head.php'; 
?>
<style>
	.back-to-projects{
		display: none;
	}   
</style>

<body class="dashboard-body">
    <?php 
    // log the user out...
    $sess_service = new UserService();
    $sess_service -> logout();
    //logout destroys the session. make sure to start a new one.
    if (session_status() == PHP_SESSION_NONE) {
        session_start();
    }
    // ...then log them in
    $already_installed = $shopify_service->checkInstallationStatus();
    $shopify_service->makeSureRecordsExist($already_installed);
    $projectid = $shopify_service->splitwit_project_id; 
    $accountid = $shopify_service->splitwit_account_id; 
    $_SESSION['accountid'] = $accountid;
    $_SESSION['userid'] =  $accountid;
    $_SESSION['email'] = $already_installed['associated_user_email'];
    
    $sess_service -> login();
    $_SESSION['active'] = true;
    include '/var/www/html/includes/experiments-ui.php'; 
    
    ?>
</body>
</html>

The method makeSureRecordsExist() checks that the SplitWit user account and project records exist, as a failsafe. The .back-to-projects CTA is hidden because Shopify users only have access to one project for their shop. The app is installed for free, while premium functionality requires a subscription after a one-week trial.

When building my second Shopify app, I started with an empty home screen UI:

<?php
require '/var/www/html/service-layer/shopify-app-service.php';
include 'shopify-creds.php';
use SplitWit\ShopifyService\ShopifyService;
$shopify_service = new ShopifyService($api_key, $secret, $app_db);
?>
<html>
<head>
</head>
<body>
   
</body>
<script>


    if(self!==top){
        // if loaded outside of an iframe, redirect away to a marketing page
        window.location = "https://www.splitwit.com";
    }


</script>
</html>

Subscription Payment

SplitWit’s codebase is originally used as a non-Shopify, stand-alone, web app SAAS. It uses Stripe as a payment gateway. Shopify requires apps to use their Billing API instead. To remedy this, I’m able to write Shopify specific front-end code with a simple JavaScript check. I leverage the browser’s window.self property to check if my app’s code is running in the top most window (opposed to being nested in an iFrame).

if(self!==top){
	// shopify app
	$(".activate-cta").remove();
	if(window.pastDueStatus || window.customerId.length === 0){
		$(".activate-loading").show();

		$.ajax({
			url:"/service-layer/shopify-app-service?method=createRecurringApplicationCharge",
			complete: function(response){
				console.log(response)
				//user is redirected to shopify confirmation screen
				$(".activate-loading").hide();
				$(".activate-cta-top").attr("href", response.responseText).show();
			}
		});
	}
	 
	$(".back-cta").click(function(){
		window.history.back();
	})
	$(".reset-pw-cta").hide()

}else{

	$(".activate-cta").click(function(){
		$(".stripe-payment-modal").show();
	});
	
	$(".back-cta").hide();
}

If it’s not the top most window, I assume the code is running in Shopify. I’ll change the click-event listener on the .activate-cta element to create a recurring subscription charge. An AJAX call is made to our PHP end-point that hits Shopify’s RecurringApplicationCharge API.

public function createRecurringApplicationCharge(){
	
	$conn = $this->conn;
	$statement = $conn->prepare("SELECT * FROM `shopify_installation_complete` WHERE splitwit_account_id = :splitwit_account_id");
	$statement->execute(['splitwit_account_id' => $_SESSION['accountid']]);
	$row = $statement->fetch();
	$shop = $row['shop'];
	$access_token = $row['access_token'];
	
	$create_recurring_charge_url = "https://" . $this->api_key . ":" . $this->secret . "@" . $shop . "/admin/api/2020-04/recurring_application_charges.json";
	$params = [
        'recurring_application_charge' => [
            'name' => 'Basic Plan',
            'price' => 25.0,
            // 'return_url' => "https://" . $shop . "/admin/apps/splitwit",
            // 'test' => true,
            'return_url' => "https://www.splitwit.com/service-layer/shopify-app-service?method=confirmSubscription"
        ]
	];
	$headers = array(
		'X-Shopify-Access-Token: ' . $access_token,
	 	'content-type: application/json'
	);
	$json_string_params = json_encode($params);

	$create_recurring_charge_curl_response_json = $this->curlApiUrl($create_recurring_charge_url, $json_string_params, $headers);
	echo $create_recurring_charge_curl_response_json['recurring_application_charge']['confirmation_url'];
}

The charge ID (delivered by the Shopify request to our ‘return_url’), payment processor, and subscription expiry date are saved to our database on call-back before returning a location header to reload the app.

public function confirmSubscription(){
	
	$conn = $this->conn;
	$statement = $conn->prepare("SELECT * FROM `shopify_installation_complete` WHERE splitwit_account_id = :splitwit_account_id");
	$statement->execute(['splitwit_account_id' => $_SESSION['accountid']]);
	$row = $statement->fetch();
	$shop = $row['shop'];
 
 	$charge_id = $_REQUEST['charge_id'];
	//write shopify billing ID to db
	$sql = "UPDATE `account` SET payment_processor = ?, billing_customer_id = ?, current_period_end = ?, past_due = 0 WHERE accountid = ?"; 
	$result = $conn->prepare($sql); 
	$current_period_end = new \DateTime();  //we need the slash here (before DateTime class name), since we're in a different namespace (declared at the top of this file)
	$current_period_end->modify( '+32 day' );
	$current_period_end = $current_period_end->format('Y-m-d H:i:s'); 
	$payment_processor = "shopify";
	$result->execute(array($payment_processor, $charge_id, $current_period_end, $_SESSION['accountid']));
	
	//redirect to app
	header('Location: ' . "https://" . $shop . "/admin/apps/splitwit");

}

That charge ID (saved to our database in a column titled “billing_customer_id”) can later be passed back to Shopify to delete the recurring charge.

Cancel a Subscription

Once a subscription is active, I can check  the payment processor saved the the account’s DB record to toggle the “cancel account” functionality from Stripe to Shopify.

<?php if ($account_row['payment_processor'] == "shopify"){ ?>
	//hit shopify service

	$(".cancel-cta").click(function(){
		//
		$.ajax({
			url:"/service-layer/shopify-app-service?method=cancelSubscription",
			complete: function(response){
				window.location.reload();
			}
		});
	});

<?php }else{ ?>
	//hit the stripe service
	
	$(".cancel-cta").click(function(){
		$(".cancel-subscription-modal").show();
	});

<?php }?>

The cancelSubscription method hits the same Shopify recurring_application_charges API, but uses a DELETE request. It also deletes the Shopify billing ID from our records.

public function cancelSubscription(){
	
	$conn = $this->conn;
	$statement = $conn->prepare("SELECT * FROM `shopify_installation_complete` WHERE splitwit_account_id = :splitwit_account_id");
	$statement->execute(['splitwit_account_id' => $_SESSION['accountid']]);
	$row = $statement->fetch();
	$shop = $row['shop'];
	$access_token = $row['access_token'];

	$statement = $conn->prepare("SELECT * FROM `account` WHERE accountid = :accountid");
	$statement->execute(['accountid' => $_SESSION['accountid']]);
	$account_row = $statement->fetch();
	$charge_id = $account_row['billing_customer_id'];


	$delete_recurring_charge_url = "https://" . $this->api_key . ":" . $this->secret . "@" . $shop . "/admin/api/2020-04/recurring_application_charges/#" . $charge_id . ".json";

	$params = [];
	$headers = array(
		'X-Shopify-Access-Token: ' . $access_token,
	 	'content-type: application/json'
	);
	$json_string_params = json_encode($params);
	$delete = true;

	$delete_recurring_charge_curl_response_json = $this->curlApiUrl($delete_recurring_charge_url, $json_string_params, $headers, $delete);

	//delete shopify billing ID from db
	$empty_string = "";
	$sql = "UPDATE `account` SET payment_processor = ?, billing_customer_id = ? WHERE accountid = ?"; 
	$result = $conn->prepare($sql); 
	$result->execute(array($empty_string, $empty_string, $_SESSION['accountid']));
	
	echo $delete_recurring_charge_curl_response_json;


}

I can use these same recurring application API end-point functions with minimal adjustments for other Shopify apps that I build. After refactoring, I am able to specify an app database as a GET parameter in the AJAX calls to my Shopify PHP service.

Uninstall the App

delete shopify app

Merchants can choose to delete apps from their shop. This will remove it from their list of installed apps. If they try installing it again, they will be re-promoted for permissions. When an app is deleted, a webhook is notified so that code can handle server-side uninstall logic:

The payment processor and billing ID associated with the merchant’s account is set to an empty string. The ‘shopify_installation_complete’ shop record is deleted.

public function uninstallApplication(){
	$conn = $this->conn; 
	
	$res = '';
	$hmac_header = $_SERVER['HTTP_X_SHOPIFY_HMAC_SHA256'];
	$topic_header = $_SERVER['HTTP_X_SHOPIFY_TOPIC'];
	$shop_header = $_SERVER['HTTP_X_SHOPIFY_SHOP_DOMAIN'];
	$data = file_get_contents('php://input'); //similar to $_POST
	$decoded_data = json_decode($data, true);
	$verified = $this->verifyWebhook($data, $hmac_header);

	if( $verified == true ) {
	  if( $topic_header == 'app/uninstalled' || $topic_header == 'shop/update') {
	    if( $topic_header == 'app/uninstalled' ) {
			$domain = $decoded_data['domain'];

			$statement1 = $conn->prepare("SELECT * FROM `shopify_installation_complete` WHERE shop = ?");
			$statement1->execute(array($domain));
			$row = $statement1->fetch();
			$accountid = $row['splitwit_account_id'];

			//delete shopify billing ID from db
			$empty_string = "";
			$result = $conn->prepare("UPDATE `account` SET payment_processor = ?, billing_customer_id = ? WHERE accountid = ?"); 
			$result->execute(array($empty_string, $empty_string, $accountid));

			$statement = $conn->prepare("DELETE FROM `shopify_installation_complete` WHERE shop = ?");
			$statement->execute(array($domain));

	    } else {
	      $res = $data;
	    }
	  }
	} else {
	  $res = 'The request is not from Shopify';
	}

}

Any webhook requests have the HMAC delivered as a header (instead of a query param, as in the case of oAuth requests) and is processed differently. “The HMAC verification procedure for OAuth is different from the procedure for verifying webhooks“. The method verifyWebhook() takes care of it:

public function verifyWebhook($data, $hmac_header){
  $calculated_hmac = base64_encode(hash_hmac('sha256', $data, $this->secret, true));
  return hash_equals($hmac_header, $calculated_hmac);
}

Cache Busting

When project changes are recorded in the app, the merchant’s snippet file is updated. We need to be sure that their website recognizes the latest version. In a separate class (that handles project & snippet logic) I make a HTTP request to my method that re-writes the script tag.

public function updateSnippetScriptTag(){
	$projectid = $_GET['projectid'];
	$conn = $this->conn;
	$sql = "SELECT * FROM `shopify_installation_complete` WHERE splitwit_project_id = ?"; 
	$result = $conn->prepare($sql); 
	$result->execute(array($projectid));
	$row = $result->fetch(\PDO::FETCH_ASSOC);
	$number_of_rows = $result->rowCount();
	if($number_of_rows == 1){
		$access_token = $row['access_token'];
		$shop = $row['shop'];
		$sql = "SELECT * FROM `project` WHERE projectid = ?"; 
		$project_result = $conn->prepare($sql); 
		$project_result->execute(array($projectid));
		$project_row = $project_result->fetch(\PDO::FETCH_ASSOC);
		$snippet = $project_row['snippet'];			

		$script_tag_url = "https://" . $this->api_key . ":" . $this->secret . "@" . $shop . "/admin/api/2020-04/script_tags.json";
		$headers = array(
		  'X-Shopify-Access-Token:' . $access_token,
		  'content-type: application/json'
		);
		$params = [];
		$json_string_params = json_encode($params);
		$use_post = false;
		//get existing script tag
		$get_script_curl_response_json = $this->curlApiUrl($script_tag_url, $json_string_params, $headers, $use_post);
		$tags = $get_script_curl_response_json['script_tags'];
	
		foreach ($tags as $tag) {
			$id = $tag['id'];
			$delete_script_tag_url = "https://" . $this->api_key . ":" . $this->secret . "@" . $shop . "/admin/api/2020-04/script_tags/" . $id . ".json";
			$use_delete = true;
			$delete_script_curl_response_json = $this->curlApiUrl($delete_script_tag_url, $json_string_params, $headers, $use_post, $use_delete);
		}
		 
		//add snippet
		$snippet = "https://www.splitwit.com/snippet/" . $snippet . "?t=" . time();
		$params = [
			'script_tag' => [
				'event' => 'onload',
				'src' => $snippet 
			]
		];
		$json_string_params = json_encode($params);
		$create_script_curl_response_json = $this->curlApiUrl($script_tag_url, $json_string_params, $headers);	 

	}
}

Once our Shopify app is built and tested we can begin to prepare for submission to the Shopify App Market.

Preparing for production

Shopify allows you to test your app on a development store.

After debugging your code locally, make sure it works end-to-end in Shopify’s environment.

test your app on Shopify

Even though the app is “unlisted”, and has not yet been accepted into the Shopify App Market, you’ll still be able to work through the entire UX flow.

install an unlisted app

GDPR mandatory webhooks

Each app developer is responsible for making sure that the apps they build for the Shopify platform are GDPR compliant.” Every app is required to provide three webhook end-points to help manage the data it collects. These end-points make requests to to view stored customer data, delete customer data, and delete shop data.  After handling the request, an HTTP status of 200/OK should be returned. PHP lets us do that with its header() function:

header("HTTP/1.1 200 OK");

These GDPR webhook subscriptions can be managed on the “App setup” page.

gdpr webhook settings

App Listing

Before submitting your app to the Shopify App Market, you’ll need to complete “Listing Information”. This section includes the app’s name, icon, description, pricing details, and more. It is encouraged to include screenshots and a demonstration video. Detailed app review instructions, along with screenshots and any on-boarding information, will help move the approval process along more quickly.

app review instructions in the app listing section of Shopify

Approval Process

Complete the setup and listing sections, and submit your app.

shopify app listing issues

You’ll receive an email letting you know that testing will begin shortly.

email from shopify

You may be required to make updates based on feedback from Shopify’s review process. After making any required changes, your application will be listed on the Shopify App Store. Below is an example of feedback that I had received:

Required changes from Shopify's app review process

To remedy the first required change I added additional onboarding copy to the app’s listing and included a demonstration YouTube video.

The second point was fixed by stopping any links from opening in new tabs. (Although, the reviewer’s note about ad blocking software stopping new tabs from opening is bogus).

The third issue was resolved by making sure the graphic assets detailed in my app listing were consistent.

Soon after making these changes, my app was finally approved and listed.

Keep Building

While writing this article I extended and refactored my PHP code to support multiple apps. I added configuration files to keep database settings modular. The Shopify PHP class can serve as back-end to several implementations. If you have any questions about how to build a Shopify app, or need my help, send me a message.

Update:

I wrote a subsequent post about building another Shopify app. It’s called SplitWit Click to Call. It explains the creative details that go into shipping a fulling working SAAS. I dive into new features that are only available to Shopify themes running the latest OS2.0 experience.

Using Stripe for SAAS payments

Letting users pay for your software service is important part of building a “Software as a Service” business. Accepting payment requires a third-party service, such as Stripe. Their PHP library makes it easy to accept credit cards and subscribe users to monthly payment plans. My examples use version 6.43. The Stripe JavaScript library is used to create secure UI elements that collect sensitive card data.

Before any coding, log into your Stripe account. Create a product with a monthly price. That product’s API ID is used to programmatically charge users and subscribe them recurring billing.

stripe product dashboard

User Interface

My software product gives users a 7-day free trial before core functionality is disabled. When they decide to activate their account they are presented with a credit card input user interface.

activate account subscription

It is built with basic HTML and CSS.

<style type="text/css">
	#card-element{
		width: 100%;
		margin-bottom: 10px; 
	}
	.StripeElement {
	  box-sizing: border-box;

	  height: 40px;

	  padding: 10px 12px;

	  border: 1px solid transparent;
	  border-radius: 4px;
	  background-color: white;

	  box-shadow: 0 1px 3px 0 #e6ebf1;
	  -webkit-transition: box-shadow 150ms ease;
	  transition: box-shadow 150ms ease;
	}

	.StripeElement--focus {
	  box-shadow: 0 1px 3px 0 #cfd7df;
	}

	.StripeElement--invalid {
	  border-color: #fa755a;
	}

	.StripeElement--webkit-autofill {
	  background-color: #fefde5 !important;
	}
</style>

<div id="stripe-payment-modal" class="modal stripe-payment-modal" style="display: none;">

	<!-- Modal content -->
	<div class="modal-content">
		<p>
		  <button type="button" class="dismiss-modal close" >&times;</button>
		</p>
		<p>Activate your account subscription.</p>
		<p><?php echo $price_point; ?> per month.</p>
		<form id="payment-form">
		  <div class="form-row">
		    <!-- <label for="card-element">
		      Credit or debit card
		    </label> -->
		    <div id="card-element">
		      <!-- A Stripe Element will be inserted here. -->
		    </div>

		    <!-- Used to display Element errors. -->
		    <div id="card-errors" role="alert"></div>
		  </div>

		  <button type="button" class="btn submit-payment">Submit Payment</button>
		</form>

  	</div>

</div>

The actual input elements are generated by Stripe’s JS. The Stripe form handles real-time validation and generates a secure token to be sent to your server.

<script src="https://js.stripe.com/v3/"></script>
<script type="text/javascript">

	$(document).ready(function() {
		// var stripe = Stripe('pk_test_xxxx'); //sandbox
		var stripe = Stripe('pk_live_xxxx');

		var elements = stripe.elements();

		// Custom styling can be passed to options when creating an Element.
		var style = {
		  base: {
		    color: '#32325d',
		    fontFamily: '"Helvetica Neue", Helvetica, sans-serif',
		    fontSmoothing: 'antialiased',
		    fontSize: '16px',
		    '::placeholder': {
		      color: '#aab7c4'
		    }
		  },
		  invalid: {
		    color: '#fa755a',
		    iconColor: '#fa755a'
		  }
		};

		// Create an instance of the card Element.
		var card = elements.create('card', {style: style});

		// Add an instance of the card Element into the `card-element` <div>.
		card.mount('#card-element');

		// Handle real-time validation errors from the card Element.
		card.addEventListener('change', function(event) {
		  var displayError = document.getElementById('card-errors');
		  if (event.error) {
		    displayError.textContent = event.error.message;
		  } else {
		    displayError.textContent = '';
		  }
		});

		// Handle form submission.
		var form = document.getElementById('payment-form');
		form.addEventListener('submit', function(event) {
		  event.preventDefault();

		  stripe.createToken(card).then(function(result) {
		    if (result.error) {
		      // Inform the user if there was an error.
		      var errorElement = document.getElementById('card-errors');
		      errorElement.textContent = result.error.message;
		    } else {
		      // Send the token to your server.
		      stripeTokenHandler(result.token);
		    }
		  });
		});

		// Submit the form with the token ID.
		function stripeTokenHandler(token) {
		  // Insert the token ID into the form so it gets submitted to the server
		  var form = document.getElementById('payment-form');
		  var hiddenInput = document.createElement('input');
		  hiddenInput.setAttribute('type', 'hidden');
		  hiddenInput.setAttribute('name', 'stripeToken');
		  hiddenInput.setAttribute('value', token.id);
		  form.appendChild(hiddenInput);
		 
		  var data = $("#payment-form").serialize();
		  $.ajax({
		  	url:"/service-layer/stripe-service?method=subscribe",
		  	method: "POST",
		  	data: data,
		  	complete: function(response){
		  		console.log(response);
		  		window.location.reload();
		  	}
		  })
		}

		$(".submit-payment").click(function(){
			stripe.createToken(card).then(function(result) {
		    if (result.error) {
		    	// Inform the customer that there was an error.
		    	var errorElement = document.getElementById('card-errors');
		    	errorElement.textContent = result.error.message;
		    } else {
				$(".submit-payment").attr("disabled", "disabled").html('Working <i class="fas fa-spinner fa-spin"></i>');
		      	// Send the token to your server.
		      	stripeTokenHandler(result.token);
		    }
		  });
		});

	});

</script>

After referencing the CDN JS library, the Stripe object accepts a public API key. That object then creates a customizable element that can be mounted into an existing <div> on your webpage. In your JavaScript, you can either listen for the form to be submitted or for an arbitrary button to be clicked. Then, we rely on the Stripe object to create a card token, which we can pass along to our back-end service.

Creating a subscription

Once the token is passed along to the server, it can be used to subscribe to the monthly product. We will need to load the PHP library and provide our secret API key. The key can be found in Stripe’s web dashboard.

require_once('/stripe-php-6.43.0/init.php');
\Stripe\Stripe::setApiKey('sk_live_XXXXXXX');

A Stripe customer ID is needed to create the subscription. Our code checks if the user record already has a Stripe customer ID saved to our database (in case they signed up previously, and cancelled).  If not, we call the “customer create” method first.

function subscribe(){
	$stripe_token = $_POST['stripeToken'];
	$conn = $this->connection;
	
	if(isset($_SESSION['email'])){
		$email = $_SESSION['email'];
	}else{
		die("No email found.");
	}
	
	if(strlen($email)>0){
		$sql = "SELECT * FROM `account` WHERE email = ?"; 
		$result = $conn->prepare($sql); 
		$result->execute(array($email));
		$row = $result->fetch(PDO::FETCH_ASSOC);
	}
	$customer_id = $row['billing_customer_id'];
	//check if this account already has a billing_customer_id
	if(strlen($customer_id) < 1){
		//if not, create the customer
		$customer = \Stripe\Customer::create([
		  'email' => $email,
		  'source' => $stripe_token,
		]);
		$customer_id = $customer['id'];
		//write stripe ID to db
		$sql = "UPDATE `account` SET billing_customer_id = ? WHERE email = ?"; 
		$result = $conn->prepare($sql); 
		$result->execute(array($customer_id, $email));
	}

	// Create the subscription
	$subscription = \Stripe\Subscription::create([
	  'customer' => $customer_id,
	  'items' => [
	    [
	      // 'plan' => 'plan_FjOzMSMahyM7Ap', //sandbox.
	      'plan' => 'price_1He7vwLjg3FTECK8lb3GDQhV', //"basic" plan. setup in Stripe dashboard.
	    ],
	  ],
	  'expand' => ['latest_invoice.payment_intent'],
	  'billing_cycle_anchor' => time()
	]);
	$subscription_status = $subscription['status'];
	$subscription_id = $subscription['id'];
	if($subscription_status == "active"){
		//set current_period_end to 32 days (1 month plus some leeway) in the future. set past_due as false 
		$sql = "UPDATE `account` SET stripe_subscription_id = ?, current_period_end = ?, past_due = 0 WHERE email = ?"; 
		$result = $conn->prepare($sql);
		$past_due = false;
		$current_period_end = new DateTime;  
		$current_period_end->modify( '+32 day' );
		$current_period_end = $current_period_end->format('Y-m-d H:i:s'); 
		$result->execute(array($subscription_id, $current_period_end, $email));
	}
}

With the subscription complete, their account’s “past due” property is marked as false and “current period end” is recorded to about 1 month in the future. The Stripe subscription ID is recorded for later use and reference.

Subscription life-cycle workflow

The application knows if an account is paying for premium service based on that “past due” property. After a user first signs up, that value is managed by a nightly scheduled cron job. If the “current period end” date is in the past, “past due” is marked as true, all projects are turned off, and a notification email is sent.

function checkPastDue(){	
	$sql = "SELECT * FROM `account` WHERE past_due = '0'";
	$result = $conn->prepare($sql); 
	$result->execute(); 
	$rows = $result->fetchAll(PDO::FETCH_ASSOC);
	$number_of_rows = $result->rowCount();
	
	include 'send-email-service.php';	

	foreach ($rows as $key => $value) {
		$current_period_end = $value['current_period_end'];
		$date = new DateTime($current_period_end);
		$now = new DateTime();
		if($date < $now) {
		   
		    //extend their trial 1 time, for an additional week
		    $extended_trial = $value['extended_trial'];
		    $accountid = $value['accountid'];
		    $email = $value['email'];
		    $billing_customer_id = $value['billing_customer_id'];
		    if($extended_trial == 0 && strlen($billing_customer_id) == 0){

		    	$sql = "UPDATE `account` SET extended_trial = '1' WHERE accountid = ?";
				$result1 = $conn->prepare($sql); 
				$result1->execute(array($accountid)); 

				$current_period_end = new DateTime;  
				$current_period_end->modify( '+8 day' );
				$current_period_end = $current_period_end->format('Y-m-d H:i:s'); 

		    	$sql = "UPDATE `account` SET current_period_end = ? WHERE accountid = ?";
				$result1 = $conn->prepare($sql); 
				$result1->execute(array($current_period_end, $accountid)); 
				 
				$SendEmailService = new SendEmailService();
				
				$subject = "SplitWit trial extended!";

				$body = "Your SplitWit trial was supposed to expire today. As a courtesy, we're extending it another 7 days!<br><br>";
				
				$altBody = "Your SplitWit trial was supposed to expire today. We're extending it another 7 days!";

				$SendEmailService -> sendEmail($subject, $body, $altBody, $email);


		    }else{
				
				$sql = "UPDATE `account` SET past_due = '1' WHERE accountid = ?";
				$result1 = $conn->prepare($sql); 
				$result1->execute(array($accountid)); 
				
				//turn off all experiments
				$status = "Not running";
				$sql = "UPDATE `experiment` set status = ? where accountid = ?";
				$result2 = $conn->prepare($sql); 
				$result2->execute(array($status, $accountid));


				//update all snippets for this account (1 snippet per project)
				$sql = "SELECT * FROM `project` WHERE accountid = ?";
				$result3 = $conn->prepare($sql); 
				$result3->execute(array($accountid));
				$rows3 = $result3->fetchAll(PDO::FETCH_ASSOC);
				foreach ($rows3 as $key3 => $value3) {
					$projectid = $value3['projectid'];
			    	$write_snippet_service = new ProjectService();
					$write_snippet_service -> writeSnippetFile(false, false, $projectid);
				}
				
				$SendEmailService = new SendEmailService();
				$subject = "SplitWit account past due";

				$body = "Your SplitWit account is past due. Please login to your account and update your payment information to continue running A/B experiments.<br><br>";
				
				$body .= "A/B testing helps you increase conversion rates and avoid unnecessary risk. <a href='https://www.splitwit.com/blog/'>Check out the SplitWit blog for experiment ideas</a>. Remember, everything is testable!";
				 
				$body .= "<br><br><a href='https://www.splitwit.com/'><img src='https://www.splitwit.com/img/splitwit-logo.png'></a>";

				$altBody = "Your SplitWit account is past due. Please login to your account and update your payment information to continue running A/B experiments. A/B testing helps you increase conversion rates and avoid unnecessary risk. Check out the SplitWit blog for experiment ideas: https://www.splitwit.com/blog/ ";

				$SendEmailService -> sendEmail($subject, $body, $altBody, $email);

		    }
			
		}
	}

}

The “current period end” date is updated each month after the customer is invoiced.

webhook payment success

When the Stripe “payment succeeded” event happens, a webhook triggers our custom end-point code.

function webhookPaymentSuccess(){
	$payload = @file_get_contents("php://input"); 
	$endpoint_secret = "whsec_XXXX";

	$sig_header = $_SERVER["HTTP_STRIPE_SIGNATURE"];
	$event = null;

	try {
	  $event = \Stripe\Webhook::constructEvent(
	    $payload, $sig_header, $endpoint_secret
	  );
	} catch(\UnexpectedValueException $e) {
	  // Invalid payload
	  http_response_code(400); // PHP 5.4 or greater
	  exit();
	} catch(\Stripe\Error\SignatureVerification $e) {
	  // Invalid signature
	  http_response_code(400); // PHP 5.4 or greater
	  exit();
	}
	
	if($event->type == 'invoice.payment_succeeded'){

		$invoice = $event->data->object;
		$customer_id = $invoice['customer'];
		//update their accocunt current_period_end
		$conn = $this->connection;
		$sql = "UPDATE `account` SET  current_period_end = ?, past_due = 0 WHERE billing_customer_id = ?"; 
		$result = $conn->prepare($sql);
		$past_due = false;
		$current_period_end = new DateTime;  
		$current_period_end->modify( '+32 day' );
		$current_period_end = $current_period_end->format('Y-m-d H:i:s'); 
		$result->execute(array($current_period_end, $customer_id));
	}else{
		http_response_code(400);
	    exit();
	}
	
	http_response_code(200);
	// var_dump($payload);
}

Although there is a webhook available for payment failure, the scheduled cron job handles that scenario.

If a user decides to cancel their subscription, we use their Stripe subscription ID and update their account records.

function cancelSubscription(){
	include '/var/www/html/service-layer/project-service.php';
	$conn = $this->connection;
	if(isset($_SESSION['userid'])){
		$accountid = $_SESSION['userid'];
	}else{
		die("No userid found.");
	}
	
	if(strlen($accountid)>0){
		
		$sql = "SELECT * FROM `account` WHERE accountid = ?"; 
		$result = $conn->prepare($sql); 
		$result->execute(array($accountid));
		$row = $result->fetch(PDO::FETCH_ASSOC);
	}
	$stripe_subscription_id = $row['stripe_subscription_id'];
	$subscription = \Stripe\Subscription::retrieve($stripe_subscription_id);
	$subscription->cancel();
	
	//#TODO: We should let the cron job handle this, so the user gets the rest of their month's service.
	//turn off experiments and update snippets. clear stripe IDs. set current_period_end to yesterday. set past_due = 1
	$current_period_end   = new DateTime;  
	$current_period_end->modify( '-1 day' );
	$current_period_end = $current_period_end->format('Y-m-d H:i:s'); 
	$sql = "UPDATE `account` SET billing_customer_id = '', stripe_subscription_id = '', past_due = 1, current_period_end = ? WHERE accountid = ?"; 
	$result = $conn->prepare($sql); 
	$result->execute(array($current_period_end, $accountid));

	//turn off all experiments
	$status = "Not running";
	$sql = "UPDATE `experiment` set status = ? where accountid = ?";
	$result2 = $conn->prepare($sql); 
	$result2->execute(array($status, $accountid));

	//update all snippets for this account (1 snippet per project)
	$sql = "SELECT * FROM `project` WHERE accountid = ?";
	$result3 = $conn->prepare($sql); 
	$result3->execute(array($accountid));
	$rows3 = $result3->fetchAll(PDO::FETCH_ASSOC);
	foreach ($rows3 as $key3 => $value3) {
		$projectid = $value3['projectid'];
    	$write_snippet_service = new ProjectService();
		$write_snippet_service -> writeSnippetFile(false, false, $projectid);
	}

	$this->status = "complete";
}

Being able to charge money for your web based software is an important step in building a SAAS business. Using a Stripe as your payment infrastructure makes it easy. Build stuff that people love and you can get paid to do it!

 

Visual Website Editor in PHP

visual editor in php

Tools for non-programmers to manage websites are growing in demand. No-code solutions increase bandwidth. Many SaaS products promise marketers and project managers a way to get things done without a developer. A visual website editor baked into an app is an important technology for digital product builders. The ability for a software service to interact with a client’s website can be a critical selling point.

SplitWit A/B Testing is an example of a web app that had that requirement. It lets user specify an existing website and displays it in an editor window. The user can then click on elements, make changes, and add new content. Those changes are actually applied to the live website by a JavaScript snippet. This post explains how it was built using PHP and jQuery.

Showing the website via iFrame

Displaying an already existing website on your app is easy with an iFrame. But, since users should be able to view and edit any page they choose, challenges arise. If a non-SSL URL is used (http:// instead of https://), the editor app will throw a “mixed-content warning”. If the page has X-FRAME-OPTIONS set to DENY, then the request will fail. To get around these issues I load an internal page into the iFrame that contains all of the DOM code from the one specified.

var pageIframe = $('<iframe id="page-iframe" style="" src="/page-to-edit.php?baseUrl='+baseUrl+'&url=<?php echo $url; ?>"></iframe>').appendTo(".page-iframe-wrapper");

The page to be edited is entered into an input field.  That 3rd party webpage’s URL is passed along to my internal “page-to-edit.php” as a query parameter. From there, I get its full code using PHP Simple HTML DOM Parser. You’ll notice that I also pass along a “base url” – which is the root domain of the page. I’m able to grab it using JavaScript.

<?php
$url = "";
if(isset($_GET['url']) && strlen($_GET['url']) > 0){
  $url = $_GET['url'];
}
?>
function removeSubdirectoryFromUrlString(url, ssl){
  
  var ssl = ssl || false;
  if(url.indexOf("https://")){
    ssl = true;
  }

  url = url.replace("http://", "");
  url = url.replace("https://", "");
  var pathArray = url.split("/")
  url = pathArray[0];
  if(ssl){
    url = "https://" + url;
  }else{
    url = "http://" + url;
  }

  return url;
}

var url = "<?php echo $url; ?>";
var ssl = false;
var pageIframe;
 
if(url.length > 0){

  if(url.indexOf("https:") !== -1){
    ssl = true
  }
   
  var baseUrl = removeSubdirectoryFromUrlString(url, ssl);
  if(baseUrl.slice(-1) !== "/"){
    baseUrl = baseUrl + "/";
  }
}

I need to append that to any assets (images, scripts, etc.) that use relative references – or else they won’t load.

<?php 
// Report all errors
error_reporting(E_ALL);
ini_set("display_errors", 1);
require 'simple_html_dom.php';


class HtmlDomParser {
	
	/**
	 * @return \simplehtmldom_1_5\simple_html_dom
	 */
	static public function file_get_html() {
		return call_user_func_array ( '\simplehtmldom_1_5\file_get_html' , func_get_args() );
	}

	/**
	 * get html dom from string
	 * @return \simplehtmldom_1_5\simple_html_dom
	 */
	static public function str_get_html() {
		return call_user_func_array ( '\simplehtmldom_1_5\str_get_html' , func_get_args() );
	}
}

$base_url = $_GET['baseUrl'];
$url = $_GET['url'];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
$html = curl_exec($ch);
$redirectedUrl = curl_getinfo($ch, CURLINFO_EFFECTIVE_URL);
$url = $redirectedUrl;

$parse = parse_url($url);

$base_url = $parse["scheme"] . "://" . $parse["host"];

$html = @HtmlDomParser::file_get_html($url);

if(substr($base_url, 0, 1) == "/"){
    $base_url = substr_replace($base_url ,"",-1);
}

if($html === FALSE) { 
    echo "Sorry, we do not have permission to analyze that website. ";
    return;
}
foreach($html->find('script') as $element){
    $src = $element->src;
    // echo "<script>console.log('starting src: ".$src."')</script>";
    
    if (strlen($src) > 0 && strpos($src, '//') === false){
        if(substr($src, 0, 1) !== "/"){
            $src = "/" . $src;
        }
        $element->src = $base_url . $src;
    }
    if(strlen($element->integrity) > 0){
        $element->integrity = "";
    }
    // echo "<script>console.log('final src: ".$base_url . $src."')</script>";

    // echo $element->src . "\n";
} 
foreach($html->find('link') as $element){
    $src = $element->href;
    
    if (strlen($src) > 0 && strpos($src, '//') === false){
        if(substr($src, 0, 1) !== "/"){
            $src = "/" . $src;
        }
        $element->href = $base_url . $src;
    }
    if(strlen($element->integrity) > 0){
        $element->integrity = "";
    }
   
}
foreach($html->find('a') as $element){
    $src = $element->href;
    
    if (strlen($src) > 0 && strpos($src, '//') === false){
        if(substr($src, 0, 1) !== "/"){
            $src = "/" . $src;
        }
        $element->href = $base_url . $src;
    } 
  
}
foreach($html->find('img') as $element){
    $src = $element->src;
    if (strlen($src) > 0 && strpos($src, '//') === false){
        if(substr($src, 0, 1) !== "/"){
            $src = "/" . $src;
        }

        $element->src = $base_url . $src;
    } 
   
}
foreach($html->find('source') as $element){
    $src = $element->srcset;
    $sources = explode(",",$src);
    $src = trim($sources[0]);

    if (strlen($src) > 0 && strpos($src, '//') === false){
        if(substr($src, 0, 1) !== "/"){
            $src = "/" . $src;
        }

        $element->srcset = $base_url . $src;
    } 
}

echo $html;

?>

I check against five different element types for assets that could need to be updated: <script>, <link>, <a>, <img>, and <source>. In version 1.0, I had missed the <link> and <source> elements.

Now that I was able to load any website into my editor UI, I had to think about layout. I split the screen in half, having the right side display the website, and the left side showing editor options.

visual website editor

Update: Eventually, I noticed that some pages were not loading properly. I found it to be two issues: a security error & a permission-denied response. The security error was a PHP problem. The permission-denied (401) response was due to server settings. Some sites don’t want to be accessed by bots and try to ensure that an actual user is making the request. I was able to fix it by passing context settings to the ‘file_get_html’ method.

$arrContextOptions=array(
    "ssl"=>array(
        "verify_peer"=>false,
        "verify_peer_name"=>false,
    ),
    "http" => array(
        "header" => "User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/50.0.2661.102 Safari/537.36"
    )
); 
$html = file_get_html($url, false, stream_context_create($arrContextOptions));

Element selection

Page-clicks in the editor window need to be intercepted to stop links from being followed and any other actions from happening. Instead, any thing clicked is selected by the editor and its details shown in the options panel.

highlight element selected

As elements are moused over, a semi-transparent red highlight is applied as a visual cue. It is achieved by injecting CSS into the iFrame and adding mouseenter and mouseout event listeners.

pageIframe.on('load', function(){
    var style = "<style>.highlighted{background-color:rgba(255, 0, 0, 0.5);} </style>";         
    pageIframe.contents().find("body").prepend(style);
     
    pageIframe.contents().find("body *").mouseenter(function(){
	$(this).addClass('highlighted'); 
    }).mouseout(function(){
	$(this).removeClass('highlighted');   
    });

});

When something is clicked, normal functionality is stopped by using the web browser’s preventDefault() method. Once the element is grabbed (using the this keyword), we want to be sure that we’re as deep into the DOM tree as possible. That way, our “Text / HTML” content won’t contain unnecessary code tags.

To do so, we use a while loop to iterate an arbitrary number of times. Eight iterations seems to be the number that gets us to the heart of any selected content, without taking too much time.

First, we check if the element has any child nodes – if it does, we grab the first one. If that node happens to be a <style> or <script> tag, we move onto the second instead. As long as that new node is not a formatting element (<strong>, <em>, etc.), we set it as the new element before continuing our loop.

testSelectorEl = $(this);
var i = 8;
while(i > 0){
	if ( $(testSelectorEl).children().length > 0 ) {
	  nextEl = $(testSelectorEl).find(">:first-child");
	  if(nextEl.is( "style" ) || nextEl.is( "script" ) || nextEl.is( "noscript" )){
	     nextEl = $(testSelectorEl).find(">:nth-child(2)");
	  }
	  if ( !nextEl.is( "u" ) && !nextEl.is( "i" ) && !nextEl.is( "strong" ) && !nextEl.is( "em" )) {
	    testSelectorEl = nextEl;
	  }
	}
	i--;
}

The above code is added to the click event listener on all elements within the iFrame. Next, below that code, we determine a unique CSS selector by which we can later reference the element. This is important for writing any changes to the JavaScript snippet to effect changes on the 3rd-party website.

var node = testSelectorEl;
var path = "";
while (node.length) {
  var realNode = node[0], name = realNode.localName;
  if (!name) break;
  name = name.toLowerCase();

  var parent = node.parent();

  var siblings = parent.children(name);
  if (siblings.length > 1) { 
      name += ':eq(' + siblings.index(realNode) + ')';
  }

  path = name + (path ? '>' + path : '');
  node = parent;
}
var value = path;
$(".selector-input").val(value);

The final iFrame on-load function looks like this:

var url = "<?php echo $url; ?>";
var ssl = false;
var pageIframe;
 
if(url.length > 0){

  if(url.indexOf("https:") !== -1){
    ssl = true
  }
   
  var baseUrl = removeSubdirectoryFromUrlString(url, ssl);
  if(baseUrl.slice(-1) !== "/"){
    baseUrl = baseUrl + "/";
  }

  var style = "<style>.highlighted{background-color:rgba(255, 0, 0, 0.5);} </style>";


  var pageIframe = $('<iframe id="page-iframe" style="" src="/new-page-to-edit.php?baseUrl='+baseUrl+'&url=<?php echo $url; ?>"></iframe>').appendTo(".page-iframe-wrapper");
     
  pageIframe.on('load', function(){

    pageIframe.contents().find("body").prepend(style);
       
    pageIframe.contents().find("body *").mouseenter(function(){

      $(this).addClass('highlighted'); 

      testSelectorEl = $(this);
        
    }).mouseout(function(){

      $(this).removeClass('highlighted');   

    }).click(function(e){

      e.preventDefault();
      e.stopPropagation();
      
      //dig deeper down the dom
      var i = 8;
      while(i > 0){
        if ( $(testSelectorEl).children().length > 0 ) {
          nextEl = $(testSelectorEl).find(">:first-child");
          if(nextEl.is( "style" ) || nextEl.is( "script" ) || nextEl.is( "noscript" )){
             nextEl = $(testSelectorEl).find(">:nth-child(2)");
          }
          if ( !nextEl.is( "u" ) && !nextEl.is( "i" ) && !nextEl.is( "strong" ) && !nextEl.is( "em" )) {
            testSelectorEl = nextEl;
          }
        }
        i--;
      }
      
      var node = testSelectorEl;
      var path = "";
      while (node.length) {
          var realNode = node[0], name = realNode.localName;
          if (!name) break;
          name = name.toLowerCase();

          var parent = node.parent();

          var siblings = parent.children(name);
          if (siblings.length > 1) { 
              name += ':eq(' + siblings.index(realNode) + ')';
          }

          path = name + (path ? '>' + path : '');
          node = parent;
      }
      var value = path;
                
      $(".selector-input").val(value); //for html insert section (redundant for change element section)
      if(! $(".insert-html-wrap").is(':visible')){
        selectNewElement(value); // prepare editor options        
        $(".page-editor-info").offset().top; //scroll user to selector input
      }
      return false;
    });

   
   //make sure images load   
   pageIframe.contents().find("img").each(function(){
      var src = $(this).attr("src");
      if(src && src.length > 0 && src.indexOf("//") == -1){  //if not absolute reference
        if(src.charAt(0) !== "/"){
          src = "/" + src;
        }
        $(this).attr("src", baseUrl + src);
      }
   });
   
   //make sure links aren't followed  
   pageIframe.contents().find("a").each(function(){
      var href = $(this).attr("href");
      $(this).attr("href", "");
      $(this).attr("data-href", href);
   });

   pageIframe.contents().find("body").attr("style", "cursor: pointer !important");
    
   $(".loading-iframe").hide();

  }); //page-iframe load
   
}else{
  //no URL found
   $(".loading-iframe").hide();
}

Lastly, we prepare the editor options panel. This involves setting the original content for the selected element and removing any newly added features (modals, sticky-bars) that were not saved.

Editor Options

After an element is clicked its content and style properties are loaded into the editor panel. The original values are stored in memory. As users edit values a change indicator icon is revealed and the right-panel editor view is updated in real time.

var testSelectorEl;
var testSelectorElPath = "";
var testSelectorElHtml = "";
var testSelectorElImage = "";
var testSelectorElLink = "";
var originalVisibilityState = "";
var originalValues = [];
originalValues['height'] = "";
originalValues['width'] = "";
originalValues['margin'] = "";
originalValues['padding'] = "";
originalValues['border'] = "";
originalValues['font-family'] = "";
originalValues['font-weight'] = "";
originalValues['font-style']= "";
originalValues['text-decoration'] = "";
originalValues['background'] = "";
originalValues['css'] = "";
originalValues['classes'] = "";

$(".html-input").keyup(function(){
    var value = $(this).val();  
    if (value !== testSelectorElHtml){
      $(this).parent().find(".change-indicator").show();
    }else{
      $(this).parent().find(".change-indicator").hide();
    }

    if($(".change-indicator").is(":visible")){
      $(".element-change-save-btn").removeAttr("disabled");
    }else{
      $(".element-change-save-btn").attr("disabled", "disabled");
    }

    var selector = $(".selector-input").val();
    var iFrameDOM = $("iframe#page-iframe").contents()
    iFrameDOM.find(selector).html(value);
    
  });

Besides changing existing elements, new ones can also be added. The “insert content” section, also based on selecting an element, lets users add new text, html, or images before or after whatever has been clicked. In both sections, the CSS selector can also be manually typed (instead of clicking). Adding or editing images is handled by a custom built image upload gallery that leverages AWS S3 and PHP.

insert content

Out-of-the-box elements, such as sticky bars and modals, can also be added with a few clicks and configurations. The HTML and CSS for those are pre-built, with variables for any options that may be set. Any changes made are saved to the database in relation to the user account, project, experiment, and variation.

function addSticky(){
	$conn = $this->connection;
	$accountid = $this->accountid;
	$variationid = $_GET['variationid'];
	$experimentid = $_GET['experimentid'];
	$text = $_POST['text'];
	$color = $_POST['color'];
	$background = $_POST['background'];
	$position = $_POST['position'];
	$linkurl = $_POST['linkurl'];

	$insertStatement = "INSERT INTO `variationchange` (accountid, variationid, experimentid, selector, changetype, changecode, content) VALUES (:accountid, :variationid, :experimentid, :selector, :changetype, :changecode, :content)";
	$changetype = "stickybar";
	$selector = "body";

	$link_opening = "";
	$link_closing = "";

	if(strlen($linkurl) > 0){
		$link_opening = "<a style='color:".$color."' href='".$linkurl."'>";
		$link_closing = "</a>";
	}

	$sticky_html = "<div style='font-weight:bold;".$position.":0;position:fixed;z-index:100000;left:0px;text-align:center;padding:8px 20px;width:100%;background:".$background.";color:".$color."' id='splitwit-sticky'><p style='margin:0px'>".$link_opening.$text.$link_closing."</p></div>";

	$changecode = '$("body").append("'.$sticky_html.'")';

	$stmt = $conn->prepare($insertStatement);	
	$stmt->bindParam(':accountid', $accountid);
	$stmt->bindParam(':variationid', $variationid);
	$stmt->bindParam(':experimentid', $experimentid);
	$stmt->bindParam(':selector', $selector);
	$stmt->bindParam(':changetype', $changetype);
	$stmt->bindParam(':changecode', $changecode);
	$stmt->bindParam(':content', $text);
	$stmt->execute();	

	$this->writeSnippetFile($variationid);
}
		

Writing changes to the snippet

Every project has a unique JavaScript file that users must add to their webpage. The file is hosted by SplitWit, so website owners only need to copy/paste a snippet. The WordPress and Shopify plugins automatically add the snippet, making it even more friendly to non-developers.

Each project may contain multiple experiments with their own changes, metrics, variations, and conditions. After the data is produced by a SQL join statement, it is massaged into a nested object and parsed in JSON. That JavaScript output is concatenated to the necessary libraries and helper functions.

function writeSnippetFile($variationid=false, $experimentid=false, $projectid=false){
	
	$conn = $this->connection;
	$variationid = $variationid || false;
	$experimentid = $experimentid || false;
	
	if(isset($_GET['variationid'])){
		$variationid = $_GET['variationid'];
	}
	if(isset($_GET['experimentid'])){
		$experimentid = $_GET['experimentid'];
	}


	if($variationid){
		$variationid = $_GET['variationid'];
		$sql = "SELECT experiment.projectid FROM `variation` right join `experiment` on variation.experimentid = experiment.experimentid WHERE variationid = ?"; 
		$result = $conn->prepare($sql); 
		$result->execute(array($variationid));
		$experiment_row = $result->fetch(PDO::FETCH_ASSOC);
	}elseif($experimentid){
		$experimentid = $_GET['experimentid'];
		$sql = "SELECT projectid FROM `experiment` WHERE experimentid = ?"; 
		$result = $conn->prepare($sql); 
		$result->execute(array($experimentid));
		$experiment_row = $result->fetch(PDO::FETCH_ASSOC);
	}
	
	if(!$projectid){
		$projectid = $experiment_row['projectid'];
	}

	$sql = "SELECT experiment.experimentid, experiment.status, experimentcondition.experimentconditionid, variation.variationid, variationchange.variationchangeid, variationchange.changecode, variation.css, variation.javascript, experimentcondition.url, experimentcondition.matchtype, experimentcondition.conditiontype, metric.metricid, metric.type, metric.input, metric.urlmatch FROM `experiment` left join `metric` on metric.experimentid = experiment.experimentid join `experimentcondition` on experimentcondition.experimentid = experiment.experimentid join `variation` on variation.experimentid = experiment.experimentid left join `variationchange` on variationchange.variationid = variation.variationid WHERE experiment.projectid = ?"; 
	
	// echo "<br />"."variationid: ".$variationid . "<br />";
	// echo "<br />"."experimentid: ".$experimentid . "<br />";
	// echo "<br />"."projectid: ".$projectid . "<br />";

	// $this->status = "SQL: " . $sql;
	$result = $conn->prepare($sql); 
	$result->execute(array($projectid));
	 
	$experiment_row = $result->fetchAll(PDO::FETCH_ASSOC);
	 
	//turn flat array, into a nested one
	$endResult = array();
	foreach($experiment_row as $row){
	    if (!isset($endResult[$row['experimentid']])){
	        $endResult[$row['experimentid']] = array(
	            'experimentid' => $row['experimentid'],
	            'status' => $row['status'],
	            'conditions' => array(),
	            'variations' => array(),
	            'metrics' => array()
	        );
	    }

	    if (!isset($endResult[$row['experimentid']]['conditions'][$row['experimentconditionid']])){
		    $endResult[$row['experimentid']]['conditions'][$row['experimentconditionid']] = array(
		        'experimentconditionid' => $row['experimentconditionid'],
		        'url' => $row['url'],
		        'matchtype' => $row['matchtype'],
		        'conditiontype' => $row['conditiontype']
		    );
		}

	    if (!isset($endResult[$row['experimentid']]['variations'][$row['variationid']])){
		    $endResult[$row['experimentid']]['variations'][$row['variationid']] = array(
		        'variationid' => $row['variationid'],
		        'javascript' => $row['javascript'],
		        'css' => $row['css'],
		        'changes' => array()
		    );
		}

	    if (!isset($endResult[$row['experimentid']]['variations'][$row['variationid']]['changes'][$row['variationchangeid']])){
		   	$endResult[$row['experimentid']]['variations'][$row['variationid']]['changes'][$row['variationchangeid']] = array(
		        'variationchangeid' => $row['variationchangeid'],
		        'changecode' => $row['changecode']
		    );
		}

	    if (!isset($endResult[$row['experimentid']]['metrics'][$row['metricid']])){
		    $endResult[$row['experimentid']]['metrics'][$row['metricid']] = array(
		        'metricid' => $row['metricid'],
		        'type' => $row['type'],
		        'input' => $row['input'],
		        'urlmatch' => $row['urlmatch']
		    );
		}
		
	}

	$json_output = json_encode($endResult);
	// echo $json_output;
	// get snippet file name.
	$sql = "SELECT snippet from `project` where projectid=?";
	$result = $conn->prepare($sql); 
	$result->execute(array($projectid));
	$projectrow = $result->fetch(PDO::FETCH_ASSOC);
	$filename = $projectrow['snippet'];
	// echo $filename;
	$snippet_template = file_get_contents("/var/www/html/snippet/snippet-template.min.js");
	// concat json to snippet template. write file			
	$myfile = fopen("/var/www/html/snippet/".$filename, "w") or die("Unable to open file!");
	//if there are any animation changes, include the necessary library.
	$txt = "";
	if(strpos($json_output, "addClass('animated") !== false){
		$txt .= 'var head=document.getElementsByTagName("head")[0],link=document.createElement("link");link.rel="stylesheet";link.type="text/css";link.href="https://www.splitwit.com/css/animate.min.css";link.media="all";head.appendChild(link); ';
	}
	$txt .= "window.splitWitExperiments = ".$json_output . "\n" . $snippet_template;
	
	fwrite($myfile, $txt) or die("Unable to save file!");

	fclose($myfile);

	//if this project is for a shopify app, we need to update the snippet cache
	$update_snippet_url = "https://www.splitwit.com/service-layer/shopify-app-service.php?method=updateSnippetScriptTag&projectid=".$projectid;
	$params = [];
	$curl_update_snippet = $this->curlApiUrl($update_snippet_url, $params);

}

One of the helper functions is a method that checks if the current URL matches the experiment’s conditions to run on:

function testUrl(testurl, conditions){
	
	if(testurl.search(/(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9][a-z0-9-]{0,61}[a-z0-9]/) < 0){
		console.log("no domain")
		return window.inputError($(".test-url-input"), "Please test a valid URL.");
	}
	var valid = false;

	for (i = 0; i < conditions.length; i++) { 
		 var url = conditions[i].url;
		 var matchtype = conditions[i].matchtype;
		 var conditiontype = conditions[i].conditiontype;

		 //exact match
		 if(matchtype == "exact" && conditiontype == "target" && url == testurl){
		 	valid = true;
		 }
		 if(matchtype == "exact" && conditiontype == "exclude" && url == testurl){
		 	valid = false;
		 }

		 //basic match
		 if(matchtype == "basic"){
		 	//strip off querystring, hashtags, protocols, and www from url and testurl - then compare
		 	var cleanTestUrl = testurl.toLowerCase();
		 	var cleanUrl = url.toLowerCase();

		 	if (cleanTestUrl.indexOf("?") > 0) {
					cleanTestUrl = cleanTestUrl.substring(0, cleanTestUrl.indexOf("?"));
				}
		 	if (cleanUrl.indexOf("?") > 0) {
					cleanUrl = cleanUrl.substring(0, cleanUrl.indexOf("?"));
				}
		 	if (cleanTestUrl.indexOf("&") > 0) {
					cleanTestUrl = cleanTestUrl.substring(0, cleanTestUrl.indexOf("&"));
				}
		 	if (cleanUrl.indexOf("&") > 0) {
					cleanUrl = cleanUrl.substring(0, cleanUrl.indexOf("&"));
				}
		 	if (cleanTestUrl.indexOf("#") > 0) {
					cleanTestUrl = cleanTestUrl.substring(0, cleanTestUrl.indexOf("#"));
				}
		 	if (cleanUrl.indexOf("#") > 0) {
					cleanUrl = cleanUrl.substring(0, cleanUrl.indexOf("#"));
				}
				cleanTestUrl = cleanTestUrl.replace(/^(?:https?:\/\/)?(?:www\.)?/i, "");
				cleanUrl = cleanUrl.replace(/^(?:https?:\/\/)?(?:www\.)?/i, "");
				cleanTestUrl = cleanTestUrl.replace(/\/$/, "");
				cleanUrl = cleanUrl.replace(/\/$/, ""); //remove trailing slash

				// console.log(cleanTestUrl);
				// console.log(cleanUrl);
				if(conditiontype == "target" && cleanUrl == cleanTestUrl){
					valid = true;
				}
				if(conditiontype == "exclude" && cleanUrl == cleanTestUrl){
					valid = false;
				}

		 }
		 
		 //substring match
		 if(matchtype == "substring"){
		 	if(testurl.includes(url) && conditiontype == "target"){
					valid = true;
		 	}
		 	if(testurl.includes(url) && conditiontype == "exclude"){
					valid = false;
		 	}
		 }
		 
	} //end conditions loop
	
	$(".test-url-msg").hide();		
	if(valid){
		$(".valid-msg").fadeIn();
	}else{
		$(".invalid-msg").fadeIn();
	}

}

While the snippet code is specific to this use-case (experimental A/B UI changes), the visual editor can be used in a variety of other contexts. You can look through more of the code I used in this GitHub repository I created.