JavaScript – Ant Pace Blog

May 1, 2024May 30, 2024

Secure Your Website: Implementing reCAPTCHA on Contact Forms

reCAPTCHA for Contact Forms to Enhance Website Security

I first explored reCAPTCHA for this website’s contact form. After getting too many spam messages, I decided to add some protection. It is Google’s implementation of CAPTCHA (reimagined) and has a long history.

The Turing Test is a concept introduced by the British mathematician and computer scientist Alan Turing in 1950 as a way to evaluate a machine’s ability to exhibit intelligent behavior indistinguishable from that of a human. The test is named after Alan Turing, who proposed it in his paper titled “Computing Machinery and Intelligence.” The history of CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart) traces back to the late 1990s when researchers began exploring ways to distinguish between humans and automated scripts or bots online.

Google’s reCAPTCHA service requires you to register the website you’re going to use it on:

It provides “Up to 1,000,000 assessments/month at no cost”. Once registered you’ll get a site key (for the client side) and a secret key (for the server side).

PHP & JavaScript Implementation

You can use the keys to implement the Google reCAPTCHA service on a vanilla website. In your HTML contact form, you need to add the site key as an empty `<div> element’s `sitekey` data attribute:

<form id="contactForm">
    <div class="">
        <div><input type="text" placeholder="Name" name="name" value="" class=""></div>
        <div><input type="email" placeholder="Email" value="" name="email" class=""></div>            
        <div><textarea placeholder="Message" rows="3" name="message" id="contactMessage" class=""></textarea></div>
        <div class="g-recaptcha" data-sitekey="XX-SITE-KEY-HERE-XX"></div>
        <div><button type="button" id="contactMe" class="btn">Send</button></div>
    </div>
</form>

The `.g-recaptcha` is transformed to a hidden input and visible user interface by Google’s JavaScript API. The UI is a checkbox that humans can click, but bots will miss. CAPTCHA mechanisms typically present users with tasks that are easy for humans to solve but difficult for automated scripts or bots.

CAPTCHA challenges can take various forms, such as:

Text-based CAPTCHA: Users are asked to transcribe distorted or obscured text displayed in an image.
Image-based CAPTCHA: Users are prompted to identify objects, animals, or characters within a series of images.
Checkbox CAPTCHA: This is what our example here is using. Users are asked to check a box to confirm that they are not a robot. This can be combined with additional checks, such as analyzing mouse movements or browsing patterns, to verify user authenticity.
Interactive CAPTCHA: Users are presented with interactive puzzles or challenges, such as rotating objects or dragging and dropping items into specific locations.

I defer the loading of that script using lazy loading:

function captchaLazyLoad(){
	contactCaptchaTarget = document.getElementById('contactSection')
	if (!contactCaptchaTarget) {
        return;
    }
	let contactCaptchaObserver = new IntersectionObserver(function(entries, observer) {
		if (entries[0].isIntersecting) {
            var script = document.createElement('script');
		    script.src = "https://www.google.com/recaptcha/api.js";
		    document.body.appendChild(script);
            contactCaptchaObserver.unobserve(contactCaptchaTarget);
        }
	})
	contactCaptchaObserver.observe(contactCaptchaTarget);
}
captchaLazyLoad();

The assessment value is serialized with the form data and passed along via a RESTful AJAX POST request to the back-end service:

var notifications = new UINotifications();
$("#contactMe").click(function(){
	var contactMessage = $("#contactMessage").val();
	if(contactMessage.length < 1){
		notifications.showStatusMessage("Don't leave the message area empty.");
		return;
	}
	var data = $("#contactForm").serialize();
	$.ajax({
		type:"POST",
		data:data,
		url:"/contact.php",
		success:function(response){
			console.log(response)
			if(response === "bot"){
				notifications.showStatusMessage("Please confirm your humanity.");
				return;
			}
			notifications.showStatusMessage("Thank you for your message.");
			$("form input, form textarea").val("");					
		}
		
	});
});

The receiving PHP file takes the reCAPTCHA assessment value, combined with our secret key, and passes them along to Google’s “site verify” service:

$secret = "XX-SERCET-KEY-XX";
$captcha = $_POST["g-recaptcha-response"];
$verify=file_get_contents("https://www.google.com/recaptcha/api/siteverify?secret={$secret}&response={$captcha}");
$captcha_success=json_decode($verify);
if ($captcha_success->success==false) {
	echo "bot";
	die();
}

If it is a bot, we `die()`.

reCAPTCHA v3 (2018) and WordPress Contact Form 7

In 2018, Google introduced reCAPTCHA v3, a version of CAPTCHA that works invisibly in the background to assess the risk of user interactions on websites. reCAPTCHA v3 assigns a risk score to each user action, allowing website owners to take appropriate action based on the perceived risk level.

A recent WordPress client messaged me “is there anyway NOT to receive anywhere from 5-10 of these a day. ” He was referencing spam messages coming from his website’s contact form. His contact page uses Contact Form 7, a popular WordPress plugin that allows website owners to easily create and manage contact forms.

I was able to easily integrate reCAPTCHA v3 by installing a 3rd party plugin. After installation, I was able to enter the site and secret keys into the WordPress dashboard. Version 3 does not require users to check any boxes or solve any challenges – it is seamless and invisible.

March 27, 2024May 30, 2024

Engaging Website Elements: Add Typing and Backspace Effects with JavaScript

On the homepage of my website, I wanted to add an animated effect that appears to backspace some text, and type out new text. Here is a video of the final product:

There are basic JavaScript tutorial snippets that can type things out:

var currentIndex = 0;
var text = 'This is a typing effect!'; /* The text */
var typingSpeed = 50; /* The speed/duration of the effect in milliseconds */

function typeWriter() {
  if (currentIndex < text.length) {
    document.getElementById("output").innerHTML += text.charAt(currentIndex);
    currentIndex++;
    setTimeout(typeWriter, typingSpeed);
  }
}

There are also more robust libraries that could do much more, like TypeIt JS. I shy away from using libraries for small implementations, so I want to write my own vanilla solution. First, I wrapped the dynamic portion in a <span> tag with its own ID:

<h2>Need help with your<br />&nbsp;<span id="dynamicText">website?</span></h2>

I added a line break AND a non-breaking whitespace character to ensure that the changing text used a consistent amount of space. Otherwise, on smaller screen sizes, you could see elements jump as the content changes.

Here is the JavaScript that controls the animation:

  const dynamicText = document.getElementById('dynamicText');
  let originalText = dynamicText.innerText;
  const newTexts = ["app?", "database?", "UI/UX?", "AI?", "API?", "blockchain?", "website?"];
  let textIndex = 0;
  let index = originalText.length;

  function deleteText() {
    dynamicText.innerText = originalText.slice(0, index--);

    if (index >= 0) {
      setTimeout(deleteText, 100); // Adjust the timeout to control the speed of deletion
    } else if (textIndex < newTexts.length) {
      originalText = newTexts[textIndex];
      setTimeout(typeNewText, 500); // Adjust the delay before typing new text
    }
  }

  function typeNewText() {
    if (textIndex < newTexts.length) {
      const newText = newTexts[textIndex];
      index = 0;

      function type() {
        dynamicText.innerText = newText.slice(0, index++);

        if (index <= newText.length) {
          setTimeout(type, 100); // Adjust the timeout to control the speed of typing
        } else {
          textIndex++;
          if (textIndex < newTexts.length) {
            setTimeout(deleteText, 500); // Adjust the delay before deleting the text
          }
        }
      }

      type();
    }
  }

The code snippet begins by declaring a constant variable dynamicText, which stores a reference to an HTML element with the id ‘dynamicText’. This element is where the typing effect will be displayed. Following this, a variable originalText is initialized with the initial text content of the ‘dynamicText’ element. This serves as the starting point for the typing effect.

Next, an array newTexts is defined, containing a list of texts that will be typed out in sequence after the original text is deleted. These texts represent the subsequent messages to be displayed in the typing animation.

Two numerical variables, textIndex and index, are declared to keep track of the current text being typed from the newTexts array and the index within the text being typed, respectively.

The deleteText() function is responsible for deleting the original text character by character until it’s fully removed. It utilizes the setTimeout function to control the speed of deletion. Once the original text is completely deleted, the function triggers the typeNewText() function to start typing the next text from the newTexts array.

Similarly, the typeNewText() function is defined to type out the new text character by character. It also utilizes setTimeout to control the speed of typing. Once the entire new text is typed, the function updates the textIndex to move to the next text in the array and triggers the deleteText() function again to delete the typed text and repeat the process with the next text.

Blinking Cursor

To add a dynamic touch, I incorporated a blinking cursor to the typing effect. The “cursor” itself if a vertical pipe bar character: “|”. I wrapped in a <span> tag and gave it a CSS class cursor.

<h2>Need help with your<br />&nbsp;<span id="dynamicText">website?</span><span class="cursor">|</span></h2>

Making it blink was as simple as adding some CSS rules:

.cursor {
  margin-left: 5px;
  animation: blink 1s steps(1) infinite;
  font-size: .9em;
}

@keyframes blink {
  50% { opacity: 0; }
}

Finally, I remove the cursor when the final word is being typed out:

if(textIndex+1 === newTexts.length){
	var cursorElement = document.querySelector('.cursor');
	if (cursorElement) {
	cursorElement.remove();
}

I add that code to the conditional block responsible for checking if all of the words have been iterated through. The final source looks like this:

const dynamicText = document.getElementById('dynamicText');
let originalText = dynamicText.innerText;
const newTexts = ["app?", "database?", "UI/UX?", "AI?", "API?", "blockchain?", "website?"];
let textIndex = 0;
let index = originalText.length;

function deleteText() {
  dynamicText.innerText = originalText.slice(0, index--);

  if (index >= 0) {
    setTimeout(deleteText, 100); // Adjust the timeout to control the speed of deletion
  } else if (textIndex < newTexts.length) {
    originalText = newTexts[textIndex];
    setTimeout(typeNewText, 500); // Adjust the delay before typing new text
  }
}

function typeNewText() {
  if (textIndex < newTexts.length) {
    const newText = newTexts[textIndex];
    index = 0;

    function type() {
      dynamicText.innerText = newText.slice(0, index++);

      if (index <= newText.length) {
        setTimeout(type, 100); // Adjust the timeout to control the speed of typing

		if(textIndex+1 === newTexts.length){
			var cursorElement = document.querySelector('.cursor');
			if (cursorElement) {
			cursorElement.remove();
		}
        }

      } else {
        textIndex++;
        if (textIndex < newTexts.length) {
          setTimeout(deleteText, 500); // Adjust the delay before deleting the text
        }
      }
    }

    type();
  }
}

window.onload = function() {
  setTimeout(deleteText, 1500);
};

February 7, 2024October 7, 2024

Tracking Google Ad Conversions in WordPress

If you’re a business owner or marketer, you’re likely familiar with Google Ads as a strong way to drive traffic to your website. Setting it up effectively can require some technical know-how, especially when integrating with WordPress. Allow me to walk you through properly integrating Google Ads with Google Analytics and Google Tag Manager, the right way, to maximize your website’s performance and data tracking capabilities.

Why Use Google Ads for Your Website?

Google Ads is an excellent tool for driving targeted traffic to your website. By bidding on keywords relevant to your business, you can show ads to users actively searching for what you offer. But, to really understand the value of that traffic, it’s crucial to track it correctly. That’s where tools like Google Analytics and Google Tag Manager come in.

Option 1: Directly Connect Google Analytics and Google Ads with Custom JavaScript

For many businesses and marketers, a straightforward setup of Google Analytics and Google Ads is enough to track important website interactions without needing a more complex setup. If you’re looking to avoid additional tools or platforms, you can connect Google Analytics and Google Ads directly and use custom JavaScript to track key actions on your website. Here’s how to do it:

Step 1: Install Google Analytics (GA4)

To begin, you’ll need to install Google Analytics on your WordPress site. There are a couple of ways to do this:

Using a Plugin: WordPress plugins like Site Kit by Google simplify the process. After installation, the plugin will automatically insert the Google Analytics tracking code into your website, and you’ll be able to see key data like page views and user behavior within your Google Analytics dashboard.
Manual Code Insertion: If you prefer not to use a plugin, you can manually add the GA4 tracking code to your WordPress site. To do this, copy the tracking script from your Google Analytics account and paste it into your site’s header or footer file (usually found in your theme settings or via your website’s code editor). This will start collecting data immediately.

Step 2: Link Google Analytics to Google Ads

Once Google Analytics is set up, the next step is to link it with your Google Ads account. This will allow you to see how your ad campaigns are performing in terms of real user behavior and conversions on your website.

In Google Analytics, navigate to the Admin section and find the Google Ads Linking option under the Property settings.
Follow the prompts to link your Google Ads account. Once linked, data such as user behavior, conversions, and audience insights will flow between Google Ads and Analytics, allowing you to optimize your campaigns based on how visitors interact with your site.

Step 3: Set Up Custom JavaScript for Conversion Tracking

For more advanced tracking, you can use custom JavaScript to monitor specific actions on your site, like button clicks, form submissions, or external link redirects. Here’s how you can do this:

Google Ads Conversion Tracking: Google Ads provides a conversion tracking code that you can place directly into your website’s HTML. For example, if you want to track when users complete a form or click a specific button, you can insert this conversion tracking code into the relevant part of your site’s HTML.
- Navigate to your Google Ads account, go to Tools & Settings > Conversions, and create a new conversion action.
- Google Ads will generate a conversion tracking code that includes a JavaScript snippet. You can add this code directly into your website’s HTML (either through your WordPress editor or directly into the page code) to track actions.
Tracking Button Clicks: If you want to track a button click (for example, a “Contact Us” button), you can insert the conversion tracking code into the button’s HTML attributes. This will trigger a conversion event each time a user clicks the button, allowing you to monitor how often it leads to valuable actions on your site.
Tracking Form Submissions: Similarly, if you want to track when users submit a contact form, you can embed the conversion tracking code into the form’s submission page or thank-you page. This is especially useful for tracking lead generation or contact inquiries.

Here is a sample of the code I used:

<script>
document.addEventListener('DOMContentLoaded', function() {
    var buttons = document.querySelectorAll('.cta-consultation'); // Select all elements with the class 'cta-consultation'

    // Check if there are any buttons to avoid errors
    if (buttons.length > 0) {
        buttons.forEach(function(button) {
            button.addEventListener('click', function() {
                // Fire the Google Ads event
                gtag('event', 'conversion', {
                    'send_to': 'AW-XXX/XXX',
                    'event_callback': function() {
                        console.log('Conversion tracked!'); // Optional: for testing purposes
                    }
                });
            });
        });
    }
});
</script>

Step 4: Monitor and Optimize Conversions

Once the custom JavaScript is in place, Google Analytics will start tracking the data, and you’ll be able to see how users are interacting with your site in the Conversions section of Google Ads. Over time, you can monitor the performance of your campaigns and make adjustments to improve your return on investment (ROI).

Key Advantages of This Approach

Simple and Direct: For small or less complex websites, directly connecting Google Analytics and Google Ads using custom JavaScript is a simple and effective solution.

Option 2: Integrating Google Analytics and Google Ads Using Google Tag Manager

For businesses that want more flexibility and control over their tracking setup, using Google Tag Manager (GTM) offers a more advanced approach compared to directly connecting Google Analytics (GA4) and Google Ads. By connecting GA4 through GTM and setting up Google Ads to pull conversion data from GA4, you can streamline the process and enable more precise tracking, including custom click tracking. Here’s how to do it:

Step 1: Set Up Google Analytics (GA4) Through Google Tag Manager

Instead of directly embedding Google Analytics code into your WordPress site, you can set up GA4 using Google Tag Manager. This allows for more flexibility in managing and customizing tracking tags without manually editing the site code. Be careful to not have it set up twice (once directly on its own, and also in GTM), or else you may see double measurements

Install Google Tag Manager on Your WordPress Site

First, install GTM by either using a plugin like Site Kit by Google or manually adding the GTM container code to your site’s header. This will serve as the foundation for all tracking scripts on your site.

Create a GA4 Tag in GTM:
- In GTM, create a new tag by selecting Google Analytics: GA4 Configuration.
- Add your GA4 Measurement ID (found in your Google Analytics account) to the tag configuration.
- Set the trigger to All Pages, so it tracks page views across your entire site.
- Save and publish the changes in GTM, and your website will now be tracking page views and user behavior through GA4 without needing any code embedded directly in your site.

Step 2: Set Up Custom Click Tracking Through GTM Triggers

One of the major advantages of using Google Tag Manager is the ability to create custom triggers to track specific user interactions, such as button clicks or link clicks, without having to modify the site’s code.

Create a Click Trigger in GTM

To track specific interactions like button clicks, you’ll need to set up a trigger in GTM. In GTM, create a new Trigger and select the Click – All Elements option. Define the conditions for your trigger, such as when a user clicks a specific button or link. For example, if you want to track a button leading to a third-party calendar page, you can set the trigger to fire when a user clicks on the button with that specific URL. My conversion was based on clicking any button or link that led to a Google Calendar scheduling page. Since the editor we were using (Kubio) generated complex HTML around the button, I was having trouble targeting exact clicks. Ultimately, I used a selector that targeted click URLs that contained part of the destination:

On another setup, I had to target “Just Links” for the event to fire. Make sure you test in preview mode to make sure it works!

Create a Google Analytics Event Tag:
- Create a new Google Analytics: GA4 Event tag in GTM.
- Set the event parameters, such as what action or label you want to track (e.g., “Button Click” or “Contact Form Submission”).
- Assign the click trigger you just created to this tag, so it fires when the user interaction happens.

Once your trigger is firing, the event will be recorded in GA4. This allows you to see detailed analytics on how users interact with specific elements on your site. You may have to wait until the next day to see it showing up and to continue the rest of this process.

Step 3: Link Google Ads to GA4 for Conversion Tracking

Once GA4 is collecting conversion data, you’ll want to make sure that Google Ads is also using this data for your ad campaigns. Instead of directly adding Google Ads tracking code to your website, you can import conversions from GA4 into Google Ads. Make sure you mark the event as a ‘Key Event’ in GA4:

Link Google Ads to GA4: In your Google Analytics admin settings, find the Google Ads Linking option under the Property settings and link your Google Ads account.
Import Conversions into Google Ads: In your Google Ads account, navigate to Tools & Settings > Conversions. Click to import conversions from Google Analytics. You will now be able to track and optimize your Google Ads campaigns based on the conversion events recorded in GA4.

Step 5: Set Up Google Ads to Track Click Conversions

With the custom click tracking events flowing into GA4, you can now import these events into Google Ads as conversions.

In GA4, mark the click event you created as a Conversion (similar to how you would for other key actions).

Then, in Google Ads, import the conversion from GA4, so your ad campaigns can track the performance of these custom click actions.

This setup allows you to track highly specific user actions (like button clicks or form submissions) and optimize your Google Ads campaigns based on those actions.

GTM allows you to track custom events like button clicks, form submissions, and other interactions without modifying your site’s code. With Google Tag Manager, you can manage all of your tracking codes (for Google Analytics, Google Ads, and other tools) in one place. By pulling conversion data from GA4 into Google Ads, you can optimize your campaigns based on real user actions and get more detailed insights into how users interact with your site.

September 20, 2023May 2, 2024

Magic Squares in JavaScript

In mathematics, a “magic square” is a matrix of numbers where each row, column, and diagonal add-up to the same number. That number is called the “magic constant“. The integers used are only positive, and do not repeat. The constant sum is determined by the size of the square and is described by a formula:

M = n * ((n^2 + 1) / 2)

Facts about the properties and classifications of these numeric formations have been discussed by scholars for millennia. Knowledge of this topic goes back thousands of years, and can be found referenced throughout the world.

History & Culture

Magic squares have a fascinating historical and cultural significance, often with mystical undertones. They are mentioned in the I Ching, Brhat Samhita, and other works concerned with the transcendental and occult. They can be seen used in art, divination, perfumery, recreational gaming, computer science, and more.

a computer programmer using the Brhat Samhita to generate a talismans — AI images generated using Midjourney

In the Brhat Samhita, the magic square is used as a symbolic representation of the planets. It makes use of magic squares in the creation of talismans for astrological purposes.

For the purposes of this blog post, we’ll view them through the lens of software engineering.

3×3 Magic Squares

There’s so much to cover on this topic. I’ll narrow it down to 3×3 lattices (magic squares can actually be any size), specifically in the context of the JavaScript programming language. A quad of numbers, like the one pictured above, can be described as a two-dimensional array:

const magicSquare = [[4, 9, 2], [3, 5, 7], [8, 1, 6]];

Squares of this size always have a magic constant of 15. And, the number 5 will be in the middle. There’s additional logic that explains which numerals can appear where and why. Those ideas are explored in the comments section of a HackerRank coding challenge titled “Forming a Magic Square”.

HackerRank Coding Challenge

This coding problem found on HackerRank asks programmers to figure out what it would take to convert a 3×3 matrix of integers into a magic square. The input array is almost valid, but requires a few replacements. For each change, we must track the difference between the numbers and return the total variance – referred to as the “cost”. The correct answer will be the lowest cost required to convert the input data into a magic square.

The difficulty of this assignment is considered “medium”. The first step is realizing that there are a finite number of valid magic square configurations. As it turns out, there are exactly eight 3×3 permutations:

const magicSquares = [[[4, 9, 2], [3, 5, 7], [8, 1, 6]], 
                [[6, 1, 8], [7, 5, 3], [2, 9, 4]], 
                [[8, 1, 6], [3, 5, 7], [4, 9, 2]], 
                [[2, 9, 4], [7, 5, 3], [6, 1, 8]], 
                [[8, 3, 4], [1, 5, 9], [6, 7, 2]], 
                [[4, 3, 8], [9, 5, 1], [2, 7, 6]], 
                [[6, 7, 2], [1, 5, 9], [8, 3, 4]], 
                [[2, 7, 6], [9, 5, 1], [4, 3, 8]]];

Starting with any one of these, we can generate the other seven programmatically. The subsequent arrangements can be derived through rotation and reflection. Using JavaScript, I rotate an initial seed square three times to have the first four series. Then, I flip each one of those to get the final records.

function generateMagicSquares(magicSquare1){
	const magicSquares = [];
	magicSquares.push(magicSquare1);

	// we need to rotate it 3 times to get all rotations
	for(let i = 0; i < 3; i++){
		var rotation = magicSquares[i].map((val, index) => magicSquares[i].map(row => row[index]).reverse());
		// console.log(rotation)
		magicSquares.push(rotation);
	}

	// and then flip each one
	for(let i = 0; i < 4; i++){
		var flipped = magicSquares[i].map((_, colIndex) => magicSquares[i].map(row => row[colIndex]));
		magicSquares.push(flipped);
	}
	
	return magicSquares;
}

const magicSquare1 = [[4, 9, 2], [3, 5, 7], [8, 1, 6]];
const magicSquares = generateMagicSquares(magicSquare1);
console.log(magicSquares);

To solve this exercise, we’ll take the input array and compare it to each of the valid magic squares. We keep track of the cost on each iteration, and finally return the minimum.

function formingMagicSquare(s){
	const magicSquares = [[[4, 9, 2], [3, 5, 7], [8, 1, 6]], [[6, 1, 8], [7, 5, 3], [2, 9, 4]], [[8, 1, 6], [3, 5, 7], [4, 9, 2]], [[2, 9, 4], [7, 5, 3], [6, 1, 8]], [[8, 3, 4], [1, 5, 9], [6, 7, 2]], [[4, 3, 8], [9, 5, 1], [2, 7, 6]], [[6, 7, 2], [1, 5, 9], [8, 3, 4]], [[2, 7, 6], [9, 5, 1], [4, 3, 8]]];
	
	// let minCost = 100000;
	let minCost = Number.MAX_SAFE_INTEGER;
	let cost = 0;
	for(let i = 0; i < magicSquares.length; i++){
		cost = determineCost(s, magicSquares[i]);
		if(cost < minCost){
			minCost = cost;
		}
	}
	return minCost;
}

You’ll notice that the initial minimum cost is set to a very high number. As I loop through each of the valid magic squares, I check if the cost is lower than the current minimum and then replace the value.

With each comparison, subtraction is used to determine the cost to complete the transformation. That code loops through each digit of each row on both 2D arrays. The absolute value of the difference between each coordinate is tallied and returned.

function determineCost(inputArray, validMagicSquare){
	let cost = 0;
	for(let i = 0; i < 3; i++){ // each row
		
		for(let j = 0; j < 3; j++){ // each digit

			cost += Math.abs(inputArray[i][j] - validMagicSquare[i][j]);
		}
	}
	return cost;
}

The working code all stitched together looks like this:

<script>

function generateMagicSquares(magicSquare1){
	const magicSquares = [];
	magicSquares.push(magicSquare1);

	// we need to rotate it 3 times to get all rotations
	for(let i = 0; i < 3; i++){
		var rotation = magicSquares[i].map((val, index) => magicSquares[i].map(row => row[index]).reverse());
		// console.log(rotation)
		magicSquares.push(rotation);
	}

	// and then flip each one
	for(let i = 0; i < 4; i++){
		var flipped = magicSquares[i].map((_, colIndex) => magicSquares[i].map(row => row[colIndex]));
		magicSquares.push(flipped);
	}
	
	return magicSquares;
}

function determineCost(inputArray, validMagicSquare){
	let cost = 0;
	
	for(let i = 0; i < 3; i++){ // each row
		
		for(let j = 0; j < 3; j++){ // each digit

			cost += Math.abs(inputArray[i][j] - validMagicSquare[i][j]);
		}
	}

	return cost;

}

function formingMagicSquare(s){
	// const magicSquares = [[[4, 9, 2], [3, 5, 7], [8, 1, 6]], [[6, 1, 8], [7, 5, 3], [2, 9, 4]], [[8, 1, 6], [3, 5, 7], [4, 9, 2]], [[2, 9, 4], [7, 5, 3], [6, 1, 8]], [[8, 3, 4], [1, 5, 9], [6, 7, 2]], [[4, 3, 8], [9, 5, 1], [2, 7, 6]], [[6, 7, 2], [1, 5, 9], [8, 3, 4]], [[2, 7, 6], [9, 5, 1], [4, 3, 8]]];
	const magicSquare1 = [[4, 9, 2], [3, 5, 7], [8, 1, 6]];
	const magicSquares = generateMagicSquares(magicSquare1);
	
	// let minCost = 100000;
	let minCost = Number.MAX_SAFE_INTEGER;
	let cost = 0;
	for(let i = 0; i < magicSquares.length; i++){
		cost = determineCost(s, magicSquares[i]);
		if(cost < minCost){
			minCost = cost;
		}
	}
	return minCost;
}

const finalCost = formingMagicSquare([[4, 9, 2], [3, 5, 7], [8, 1, 5]]);
console.log(finalCost);
</script>

This solution was not intuitive to me and took some research and experimentation. It was interesting to learn about the concept of magic squares (and other shapes) along the way.

Additional References

March 9, 2023May 2, 2024

Binary Search in JavaScript

“Binary search” is a computer science term used in programming and software engineering. It is a way of determining if a value exists in an ordered data set. It’s considered a textbook algorithm. It is useful because it reduces the search space by half on each iteration.

Imagine we are asked to search for an integer in an array that is sorted in ascending order. The challenge is to return the target number’s index.

We could use a built in JavaScript function indexOf():

var search = function(nums, target) {
    var answer = nums.indexOf(target);
    console.log(answer);
    return answer;
};
console.log(search([-1,0,3,4,5,9,12], 5)); // returns '4'

But that is an abstraction, which can be slow and expensive. Instead, we should implement our own binary search code.

Binary Search Implementation

Binary search starts in the middle of a collection, and checks if that is the requested term. The initial middle position is determined by taking the length of the array and dividing it by two. If the array has an even number of elements, then the ‘halfway position’ is considered close enough. I use a JavaScript Math function to round down, making sure I am not left with a decimal floating number:

cursor =  Math.floor( ((left + right) / 2) ); // about the middle

If the search term is not found, the position (the cursor) is moved. Since the collection is ordered from smallest to largest we know which direction to move the search cursor. If the target is less than the current value, we shift one to the left. If the target is greater than the current value, we shift two to the right.

This continues until the target query is found. That sequence is ran inside of a loop. The loop repeats while the left boundary is less than (or equal to) the right. The search cursor’s index is changed by adjusting the left or right bounds. Once adjusted, the cursor is recalculated on the subsequent iteration.

var search = function(nums, target) {
    var left = 0; // first element, initial left boundary
    var right = nums.length;
    right = right - 1; // last element, initial right boundary
    var cursor = 0;
    while(left <= right){
        cursor =  Math.floor( ((left + right) / 2) ); // about the middle to start
        console.log(cursor + ": " + nums[cursor]);
        if(nums[cursor] === target){
            return cursor; // query found!
        }
        if(target < nums[cursor]){
            right = cursor - 1; // move cursor to the left by one
            console.log("cursor moved to the left  by one")
        }else{
            left = cursor + 1; // move cursor to the right by two
            console.log("cursor moved to the right by two")
        }
    }
    return "false"; // not found
};
console.log(search([-1,0,1,2,3,4,5,6,7,8,9,10,11,12], 10));

The above code starts to search in the central location, nums[6] == 5. Look at the output below to see how the cursor moves until it finds the target value of 10 (at a zero-based index of 11):

This algorithm has an O(log n) runtime complexity. That Big-O notation describes how it would scale as the input increases. Imagine an array with thousands of elements. O(log n) means that the time to execute this code will increase linearly only as the number of input items increase exponentially. That means our code is performant and efficient.

Square root algorithm using binary search

Another implementation example of using binary search in a JavaScript function is to calculate the square root of a number. Now, of course, Javascript has a built in Math.sqrt() function that is highly performant compared to any custom code we will write. But, it is a good exercise to think about how this works.

The square root of a number is a value that, when multiplied by itself, gives the original number. To solve for it when given an input, we are going to take a guess at what the answer (square root) is, starting with itself divided by two (giving us the midpoint between it and zero). We multiply that midpoint by itself to check our guess. It will only be correct on the first iteration if the input is the number four (four divided by two is two; two times two is four). Otherwise, we will move the cursor (halving the search range) to either the left or the right, depending on if the square of our guess is larger or smaller than the original input.

The concept of “moving the cursor” helps to visualize how the binary search algorithm zeroes in on the square root by iteratively narrowing down the search range based on the comparison of the square of the midpoint to the target number.

I accounted for two special cases in my code. For negative numbers we return false because negative numbers have imaginary square roots. For numbers smaller than one we set the range’s end to one because the square root of a fraction is larger than the fraction itself. Additionally, I set a precision threshold (0.0000000001), because some numbers have square roots that are irrational.

function binarySearchSquareRoot(n, precision = 1e-10) {
    if (n < 0) {
        throw new Error('Input must be a non-negative number');
    }

    let start = 0;
    let end = n;

    // If the number is less than 1, set end to 1 to handle fractions
    if (n < 1) {
        end = 1;
    }

    while (end - start > precision) {
        const mid = (start + end) / 2;
        const midSquared = mid * mid;

        if (midSquared === n) {
            return mid;  // Found exact square root
        } else if (midSquared < n) {
            start = mid;
        } else {
            end = mid;
        }
    }

    return (start + end) / 2;  // Return approximate square root
}

// Usage:
const number = 25;
const squareRoot = binarySearchSquareRoot(number);
console.log(`The square root of ${number} is approximately ${squareRoot}`);

Alternatively, the Babylonian algorithm can be implemented to solve for square roots.

Additional References

https://delboy1978uk.wordpress.com/2018/02/06/binary-search-trees-in-php/
https://research.google/blog/extra-extra-read-all-about-it-nearly-all-binary-searches-and-mergesorts-are-broken/

October 23, 2022January 22, 2024

React Redux Provider Store: No Overload Matches This Call

This post documents a solution for the following error I encountered in a React TypeScript project that was using Redux:

No overload matches this call.
  Overload 1 of 2, '(props: ProviderProps<Action> | Readonly<ProviderProps<Action>>): Provider<Action>', gave the following error.
    Type '{ children: Element; store: Store<{ readonly [$CombinedState]?: undefined; } & { repos: ReposState; }, Action>; }' is not assignable to type 'IntrinsicAttributes & IntrinsicClassAttributes<Provider<Action>> & Readonly<ProviderProps<Action>>'.
      Property 'children' does not exist on type 'IntrinsicAttributes & IntrinsicClassAttributes<Provider<Action>> & Readonly<ProviderProps<Action>>'.
  Overload 2 of 2, '(props: ProviderProps<Action>, context: any): Provider<Action>', gave the following error.

React is a JavaScript framework used to build web apps. Redux is an open-source library used to manage the state of an application, and is often used along with React JS.

In this context, the Redux <Provider> component is used to pass application state along to its children components. It is best practice to wrap the entirety of your app in the <Provider> component, and pass the store object into it as an argument (property):

import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import { Provider } from 'react-redux';
import App from './App';
import { store } from './state';

const root = ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement
);

root.render(
  <React.StrictMode>
    <Provider  store={store}> 
      <App />
    </Provider>
  </React.StrictMode>
);

In my project, this was producing an error on the <Provider> component that said “No overload matches this call.” I knew this must have something to with the argument(s) being passed along.

At first I thought it might have something to do with my store object, but that was not it. I was able to resolve this roadblock by explicitly passing a ProviderProps object into the Provider component.

import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import { Provider, ProviderProps } from 'react-redux';
import App from './App';
import { store } from './state';


const providerProps: ProviderProps = {
  store: store,
};

const root = ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement
);

root.render(
  <React.StrictMode>
    <Provider  {...providerProps}> 
      <App />
    </Provider>
  </React.StrictMode>
);

This worked because the store object is explicitly typed in the ProviderProps object. This ensures that it matches the type expected by the Provider component. Ultimately, it was a TypeScript error. TypeScript was not able to infer the store type correctly.

This was a bug I encountered while building a web app for an Udemy course called “React and Typescript: Build a Portfolio Project“.

September 23, 2022January 22, 2024

Memoization (Caching) and Recursion with JavaScript

A common coding challenge that you may encounter will ask you to write a function that returns the Fibonacci sequence, up to the nth number (which is provided as an argument). Below is a solution, along with some commentary about the topic. This challenge is a great exercise in problem solving.

Fibonacci numbers

The sequence starts with 0 and 1, and the next number in the sequence is always the sum of the previous two numbers. The first few terms of the sequence are:

0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610, 987, 1597, 2584, 4181, 6765, 10946, 17711, 28657, 46368, 75025, 121393, 196418, 317811

Since this series follows a known pattern, we can write code to generate it up to a specified position.

In mathematics, the Fibonacci sequence is a sequence in which each number is the sum of the two preceding ones. Numbers that are part of the Fibonacci sequence are known as Fibonacci numbers.

These numbers were first described in ancient Indian mathematics. They are named after the Italian mathematician Leonardo of Pisa, also known as Fibonacci, who introduced the sequence to Western European mathematics in his 1202 book Liber Abaci. Fibonacci numbers are also strongly related to the golden ratio. In computer science, these numbers can be applied to programming algorithms related to search, data structures, and graphs.

Recursion

In programming, recursion is an important concept. Recursion is when a function calls itself. Writing code that generates the Fibonacci sequence requires recursion. Here is an example in JavaScript:

function fibonacci(n) {
    if (n < 2){
        return 1;
    }else{
        return fibonacci(n-2) + fibonacci(n-1);
    }
}
console.log(fibonacci(7)); // Returns 21

If you ask this function for 0 or 1 terms, it will simply return 1. It is the condition that will ultimately stop the recursion. Anything above that, it will have to call itself recursively. What exactly is happening there? This Stack Overflow thread does a great job stepping though the logic and illustrating each iteration.

When I decorate the code from above with console log statements and collect the results into an array, it becomes obvious:

function fibonacci(n) {
  console.log("Iterating on n = " + n)
  if (n <= 1) {
    console.log("n is: "+n)
    return [0, 1].slice(0, n + 1);
  } else {
    const fib = fibonacci(n - 1);
    console.log("fib is: "+fib)
    console.log("iterating on " + n)
    fib.push(fib[fib.length - 1] + fib[fib.length - 2]);
    return fib;
  }
}

You can see it iterates all the way down, starting at the desired argument of term numbers, and ending with 1. Once it gets to the bottom, it starts going back up. On each subsequent round, it adds a new number to the result array by summing the previous two numbers.

I asked ChatGPT to rewrite this code for me, and this is how it was cleaned up:

function fibonacci(n) {
  if (n <= 1) {
    return [0, 1].slice(0, n + 1);
  } else {
    var sequence = fibonacci(n - 1);
    sequence.push(sequence[sequence.length - 1] + sequence[sequence.length - 2]);
    return sequence;
  }
}

This function has an exponential time complexity. It can be very slow for larger values of n.

Memoization and Cacheing

This challenge is often followed with a request to make it “more performant”. I mentioned above that our solution has “exponential time complexity”. Its algorithmic efficiency can be described as O(2^n) in Big O notation.

Every call (while n is greater than 1) results in two additional recursive calls, one with n-1 and another with n-2. Each of those calls then results in two more recursive calls, and so on, resulting in a binary tree of recursive calls.

The performance of this code can be improved by implementing memoization. Memoization is when we store the results of our function call. On subsequent calls, our application can look up answers it previously calculated without have to do the work again.

function fibonacci2(n, memo = {}) {
  if (n in memo) {
    console.log("we used the memo on: " + n)
    return memo[n];
  }
  if (n <= 1) {
    return [0, 1].slice(0, n + 1);
  } else {
    const fib = fibonacci2(n - 1, memo);
    fib.push(fib[fib.length - 1] + fib[fib.length - 2]);
    memo[n] = fib;
    return fib;
  }
}
memo = {}
console.log(fibonacci2(7, memo));
console.log(fibonacci2(15, memo));

On each iteration we save the results to an array called memo. When we use the function, we first check to see if the answer we want is already stored in our cache. Our course, the work still needs to be done the first time around, but never again – making computation much faster in the future. You can see that my 2nd call can start where the results of the previous call left off:

By using memoization, this implementation of the Fibonacci function has a time complexity of O(n). Another way to improve the performance of our code, without using memoization, is to use a loop:

function fibonacci(n) {
  var sequence = [0, 1];
  for (var i = 2; i <= n; i++) {
    sequence.push(sequence[i-1] + sequence[i-2]);
  }
  return sequence;
}

The choice between memoization or a loop depends on the specific requirements and constraints of the use-case. While the time complexity of a loop-based solution is still O(n), it can be faster than the memoization approach for small or medium-sized values of n. If simplicity and readability are a higher priority, or if memory usage is a concern, a loop-based solution may be a better option.

Memoization is considered a “dynamic programming” technique. Dynamic programming involves solving sub-problems once and storing the results for future reference, which can significantly improve the efficiency of the overall solution.

May 20, 2022January 22, 2024

Sort an HTML Table Using JavaScript

For a recent side project I was tasked with enhancing an existing HTML table. That table displayed search results. The records were dynamic, populated by an AJAX call after the “search” button was pressed. One of the requests was to let users click on the column headers to sort the table. Each click would organize the data, toggling ascending and descending, based on the column values.

My first idea was to use a front-end library. I love abstractions, and hate reinventing the wheel. I’ve used the DataTables jQuery plug-in before, and thought it might be a good fit. All I had to do was include two CDN file references – one for CSS styles and another for JavaScript functionality. After that, I could select the table by ID and call a single function:

<link href='//cdn.datatables.net/1.13.2/css/jquery.dataTables.min.css' rel='stylesheet' type='text/css'>
<script src="//cdn.datatables.net/1.13.2/js/jquery.dataTables.min.js"></script>

<script>
$(document).ready( function () {
	$('#dog-table').DataTable();
} );
</script>

This added quick and easily out-of-the-box functionality, with bells and whistles.

It seemed great, but the extras that it added, such as pagination and front-end search were unnecessary, and actually got in the way of the design specification. Those might be easy enough to clean up by passing options into the method call, or even with a bit of custom CSS, but still seemed like overkill.

Further, the DataTables library would occasionally throw errors about an “incorrect column count”, depending on what results my back-end provided. That was because the data model, and possible front-end actions for this app were more complex that you might think. The HTML wasn’t strictly semantic and the information wasn’t just tabular.

The more I thought about it, the more I felt that plain vanilla JavaScript should be enough to get the job done. And, since we’re living in the future, I decided to ask an AI chat-bot called ChatGPT.

I asked “How can I use jQuery to sort an HTML table by a specific column?”

It told me that “You can use the sort method of JavaScript arrays combined with the map method to sort an HTML table by a specific column,” and gave me a specific code example!

I was very impressed. Here is the JavaScript code it provided:

<script>
$(document).ready(function() {
  var table = $('#myTable tbody tr').get();

  table.sort(function(a, b) {
    var A = $(a).children('td').eq(1).text();
    var B = $(b).children('td').eq(1).text();

    if(A < B) {
      return -1;
    }

    if(A > B) {
      return 1;
    }

    return 0;
  });

  $.each(table, function(index, row) {
    $('#myTable').children('tbody').append(row);
  });
});
</script>

I added this code to a click-handler in my app, after adjusting the element selectors. Although it worked (kind of), it did not operate quite as I expected. It only performed the sort on a single column, and did not alternate the order on each click.

I continued to ask the chat-bot more questions, making refinements to the functionality. I wanted the code to toggle between ascending and descending on each click. Also, I figured it could be nice to avoid jQuery completely and just use basic JS.

Eventually, it told me “To toggle between ascending and descending order when sorting the table, you can keep track of the current sorting order for each column in a separate array”. Below, you can see the full code implementation:

<style>
  table {
  border-collapse: collapse;
  width: 100%;
}

th, td {
  text-align: left;
  padding: 8px;
  border-bottom: 1px solid #ddd;
}

tr:nth-child(even) {
  background-color: #f2f2f2;
}

th {
  background-color: #4CAF50;
  color: white;
  cursor: pointer;
}

td:first-child {
  font-weight: bold;
}

td:nth-child(3), td:nth-child(4) {
  text-transform: capitalize;
}
#search-input {
  padding: 8px;
  margin-bottom: 12px;
  width: 100%;
  box-sizing: border-box;
  border: 2px solid #ccc;
  border-radius: 4px;
  font-size: 16px;
}

#search-input:focus {
  outline: none;
  border-color: #4CAF50;
}
</style>
<input type="text" id="search-input" placeholder="Search breeds...">
<button>Search</button>
<table id="dog-table">
  <thead>
    <tr>
      <th>Breed</th>
      <th>Origin</th>
      <th>Size</th>
      <th>Temperament</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Labrador Retriever</td>
      <td>Canada</td>
      <td>Large</td>
      <td>Friendly, outgoing, and active</td>
    </tr>
    <tr>
      <td>German Shepherd</td>
      <td>Germany</td>
      <td>Large</td>
      <td>Loyal, confident, and courageous</td>
    </tr>
    <tr>
      <td>Poodle</td>
      <td>France</td>
      <td>Small to Large</td>
      <td>Intelligent, elegant, and proud</td>
    </tr>
    <tr>
      <td>Bulldog</td>
      <td>England</td>
      <td>Medium</td>
      <td>Determined, friendly, and calm</td>
    </tr>
    <tr>
      <td>Beagle</td>
      <td>England</td>
      <td>Small to Medium</td>
      <td>Cheerful, determined, and friendly</td>
    </tr>
  </tbody>
</table>


<script>
// Get the table element
const table = document.querySelector('table');

// Get the header row and its cells
const headerRow = table.querySelector('thead tr');
const headerCells = headerRow.querySelectorAll('th');

// Get the table body and its rows
const tableBody = table.querySelector('tbody');
const tableRows = tableBody.querySelectorAll('tr');

// Initialize sort order for each column
let sortOrders = Array.from(headerCells).map(() => null);

// Attach a click event listener to each header cell
headerCells.forEach((headerCell, index) => {
  headerCell.addEventListener('click', () => {
    // Extract the column index of the clicked header cell
    const clickedColumnIndex = index;
    
    // Toggle the sort order for the clicked column
    if (sortOrders[clickedColumnIndex] === 'asc') {
      sortOrders[clickedColumnIndex] = 'desc';
    } else {
      sortOrders[clickedColumnIndex] = 'asc';
    }
    
    // Sort the rows based on the values in the clicked column and the sort order
    const sortedRows = Array.from(tableRows).sort((rowA, rowB) => {
      const valueA = rowA.cells[clickedColumnIndex].textContent;
      const valueB = rowB.cells[clickedColumnIndex].textContent;
      const sortOrder = sortOrders[clickedColumnIndex];
      const compareResult = valueA.localeCompare(valueB, undefined, { numeric: true });
      return sortOrder === 'asc' ? compareResult : -compareResult;
    });
    
    // Rebuild the table in the sorted order
    tableBody.append(...sortedRows);
  });
});

</script>

Using predictive language models as a coding assistant is very helpful. I can’t wait to see what other uses we find for this technology, especially as it gets better.

March 7, 2021May 2, 2024

How to create 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.

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.

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.

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.

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

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.

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

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.

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.

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.

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.

Approval Process

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

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

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:

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.

Additional References

https://github.com/LukeTowers/php-shopify-api

https://weeklyhow.com/shopify-uninstall-webhook-api-tutorial

https://github.com/markrogoyski/awesome-php