Today I’m going to take you through a really brief walk through and introduction of Optimizely-CLI.
A little bit of background: we at FunnelEnvy write a lot of tests in Optimizely. We love it as a platform. But we’re also software developers and engineers, and so we like to write our tests directly in JavaScript code. It’s much faster for us, and we’re really looking for ways to be able to use a lot of the tools that we use for software development in order to write tests.
We found as we built out the CLI, which stands for Command Line Interface, that being able to do a lot of the test development and debugging locally on our own machines was actually much faster. Optimizely-CLI allows you to do that, and then when you’re ready to push it up to Optimizely, you use the Optimizely API to push your test up.
You certainly do have to do a lot of the final tweaking and edits and QA directly in Optimizely, but the largest component of tests, especially more complex tests, not just changing around a word or two or a color but tests that are significantly more involved, is writing the code and is developing it. So, hopefully, if you’re a developer writing Optimizely tests, this can have value for you.
So, let’s get into it. I’m going to skip past the installation of the optcli itself. It’s pretty straightforward. It is built on Node, so you’re going to have to have Node installed locally. It’s delivered as an NPM package, so you’re going to have do an NPM install of Optimizely-CLI. Documentation is on our page, so feel free to take a look.
Once you have installed Optimizely-CLI, what you’ll want to do is create a new directory for your project. You’ll see that this one here is empty. The first thing you’ll want to do is initialize your project. The optcli init command is the one you’ll want to use for that, and you need to specify your project ID. The easiest way to find that is to head over to Optimizely and your project and go to the project settings tab, where under snippet implementation you will see your project ID.
Now, if I look at it, optcli has created a project.json file. An empty project is, obviously, not very useful, so we want to create our first experiment. Let’s say we wanted to do a headline test on the FunnelEnvy home page. To do that, you’ll want to use the optcli experiment command which takes several arguments including the directory that you want to create the experiment in, the description of the experiment, that’s what’s going to show up in Optimizely in the dashboard and in several other places, as well as the default editor URL.
When you open it up in Optimizely, this is the page that will open. You’ll see that it has created the folder and in there is the experiment.json file that describes the experiment.
Next up, we’ll want to create a variation within that experiment. To do that, we’ll use the optcli variation command, which in a similar way takes the folder name of the experiment, the folder name of the variation, as well as the variation description.
Let’s take a closer look at the files that optcli created. As you’ll see, here’s the project. Underneath there, we’ve got the headline test experiment, and underneath there we’ve got a variation called headline test. By default, optcli will include a variation.js as part of the variation, a global.css, as well as a global.js. This corresponds to the objects within Optimizely, the variation JavaScript as well as the global CSS and the global JavaScript that take effect for all variations within the project. The JSON files, as I mentioned, in here contain metadata about the variation project and experiment.
So, let’s add a little bit of code to our variation. As I said, we’re doing some headline testing. We’re going to make some changes to this headline at the top of the FunnelEnvy home page. So, we can do that right in the variation.js on our local directory, much as you would in the Optimizely edit code window, and we can add in a bit of JavaScript right there, changing the H1 tag to “Welcome to FunnelEnvy.”
Next, we’re going to want to style that, and so we can add some CSS right in the global CSS. Keep in mind that, just as with Optimizely, the global CSS will take effect for every variation. So, let’s make the font bold. Save that.
Then, just say for illustrative purposes, put a function in the global JavaScript file. And in order to call this function, I’m actually going to go back to the variation.js and call it right from there.
So, now my initial code for the variation is set. I’ve got code in the variation JavaScript, styles in the global CSS, and a function in the global JavaScript. Once you’ve coded your variation, optcli will let you host that variation locally and preview, debug, edit, and finalize the code for the variation before you push it up to Optimizely. That lets you make sure everything is right, iterate quickly on the code, and then make the final adjustments once you’re in the Optimizely environment.
Let’s take a look at what that looks like. The way to start the local server is to use the optcli host command and specify the path to the variation. By default, optcli uses port 8080. You can change that using the command line argument. And, by default, it serves over HTTP. You can also specify minus S for SSL if you are testing on HTTPS pages. If you point your browser to the URL from the console output, you’ll see that Optimizely-CLI has some instructions as well as some status and URLs for you.
On the left hand side, there are some one time setup steps. You only need to do this once, the first time you do the local hosting and script injection with Optimizely-CLI. And on the right, you’ll see the currently served experiment and variation as well as URLs to be able to view the variation on the editor URL that you specified in the experiment.
The script injection does require either the Tampermonkey Chrome extension, if you’re on a Chrome browser, or the Greasemonkey Firefox add on. In this case, I’m on Chrome, and I have installed the Chrome extension already. So, I’ll skip ahead to step two.
Step two is installing the Optimizely-CLI user script. This is generated by optcli. It’s a relatively simple script that will inject the locally served variation and CSS, locally served JavaScript, into the page by dynamically creating elements. In this case, I’ve already installed it. I’m going to hit reinstall anyway and then come back to the tab that I was on.
Now, Tampermonkey is installed on my browser. The injection script is running. I can now actually view the variation that I created. If you take a closer look at that script, optcli uses the optcli activate parameter to determine whether or not to inject the script. So, you can actually run your variation script on any URL just by appending this parameter.
Let’s go ahead and click on the link and see the variation. You can see here that this was the function that was executed in the global JavaScript, and per the variation code, the headline has been changed and the font style has been bolded. Now if I want to go back and make a change, it’s very simple to do. If I wanted to change the text in my variation to “Welcome Fellow Optimizer”, I change that locally, save the file, go back to the browser, hit refresh, and the change is done. And let’s say I wanted to get rid of the alert. It never made a lot of sense anyway. I take that out, refresh the page again, and it’s gone.
This lets you iterate really rapidly because you are doing it locally and then can therefore move a lot faster and get your code right. Let’s say I am happy with my code for the variation now and I want to send it up to Optimizely. Go back to the command line. We can stop the local server and run the optcli push experiment. It’s important to remember that you need to have pushed the experiment before you can push any of the variations underneath it. To push a variation, you just push experiment and specify the directory of the experiment.
If you haven’t entered your Optimizely API token, you’ll need to do so now. You only need to do this once on a project. It will store this locally. I’m going to enter my token now.
So, the token’s been set, and it has created a remote experiment in Optimizely. So, let’s head back over to Optimizely. Looking at the dashboard, refreshing the page, and I can see the headline test has been created. Let me push up the variation now that I created. To do that, you use the optcli push variation command specifying the path to the variation which is obviously underneath the experiment locally. And I didn’t need to enter my token, because I’ve entered it once and you can see that the variation has been created.
One final note on both the push experiment and push variation command. You can run these multiple times. The first time for both it’ll create either an experiment or a variation. But, if you make some local changes and run it again, it will actually update the code for those variations.
That’s how you can keep your local code in sync with what’s in Optimizely. So, if I go take a look in Optimizely, you’ll see that the headline test one experiment has been created as well as the change headline variation. By default, Optimizely will create a variation number one. You can remove that if you choose.
I hope you enjoyed this brief introduction to Optimizely-CLI. There are several other features there that I haven’t mentioned, so certainly feel free to give it a spin. If you have any feedback, we’d love to hear it. Feel free to submit issues or, better yet, put requests on the GitHub page. Thank you.
