Enable users to add parameters to integration code mindfully

Question

I'm trying to design a screen that will allow our customers to generate integration code (to integrate to our application). I would like to demonstrate to the customers that they can add additional parameters to the code, although it's not necessary to do so. I also would like them to understand the syntax rather than just copy paste the code with the dummy parameters.

I came up with this screen (where value is probably going to be the most used type of additional parameter and by default nothing will be checked). Is this design clear enough? Are there standards I should follow that I'm not? Any ideas on how to make it better?

Here is a Balsamiq screenshot:

Answer 1

Make it easy.

In most of the custom built CMS projects that we do for my clients, their users have a very limited technical understanding, but not necessarily technical programming skills.

Some of the different things we've done over the years:

• If you make the site interact with the user and try to autofill or provide suggestions based on the "code" they're writing, you could potentially have the best results from a user experience standpoint. In this example, the colon is the cursor. On pause you could show a pop-up based on prior context.

• Develop a very simple core scripting language that is parsed into code. Then you would build your interpreter to change this plain language dialog into code. For example take a look at applescript. This prevents the users from breaking the code by adding their own real closing tags.

You could make it say something like:

Set user property with price 100 in currency
US and add custom field "name" with value of "ABC"

Then it would generate this by dynamically pulling their ID:

DY.setUserProperty(11345,{"value"="$100","name"="ABC"});

• For some of our clients we have a prefilled code box that shows potential code, but they need to understand the code and the we also have to provide a coding language reference (much harder to maintain and keep up to date when there is a major revision).

• We've tried to buttons to automatically inject tags into real code, but the users sometimes inject attributes outside of the code tags, or they are placed into the wrong places. This requires a much more technical user.

A combination of the first two would be an excellent interface that anyone could use. You'll also want to provide examples of the language and let the users know that they will see pop-ups when they're writing. Give them options to delay the pop-up or disable it altogether if the language is simple enough.

It does require that they allow a client-side scripting language like Javascript, although since you're having them output Javascript I would bet they should have this enabled already.