Actions on Google client library for Node.js v2.0.0

Edit: the content of this post has been changed to reflect the launch to GA.

We have just published v2 of the Actions on Google Node.js client library on GitHub.

This is a major update that lands a little over a year after we published v1 on npm. We spent this year listening to feedback from developers who used the library to build apps for the Assistant, and using the client library ourselves to write sample applications. We learned a lot :)

We rewrote the client library from the ground up: there’s a new architecture and new APIs, and we think it will allow you to write more concise and expressive code.

In this blog post, I’m going to present to you some highlights of the changes we made; for each, I’ll discuss the motivation for the change and advantages of the new design.

Modularity

Frameworks

Actions on Google developers use a variety of Node.js web frameworks to implement their fulfillment for their actions, usually depending on their preference or on what is available on the serverless platform they use to host their code. Examples of such frameworks include express, and koa. When it comes to platforms, some use Cloud Functions for Firebase,while others use one of the many other available options.

In V1 of the client library, working with frameworks other than express requires you to fork the client library and modify the code, because we assume that request and response are in express format.

In V2, we added a Framework system that allows for easy integration of the library in any Node.js web framework. A web framework like Express/Lambda/Koa can be represented in the library as a class that can handle requests coming from a specific framework.

While you don’t need to know all the details about how the Framework system works unless you want to add support for a framework not currently supported, you will certainly appreciate how easy it becomes to serve the same app from different platforms/frameworks.

Cloud Functions for Firebase:

AWS Lambda:

Self-hosted express:

Plugins

We’ve added a plugin system to make it easier to integrate small modules of code that implement optional functionalities, like managing string localization, adding variation in responses using randomization from a pool of candidates, or even adding support for a new web framework like in this example.

If you ever wrote some code to implement something that you wished the client library would already do, you can now share it more easily with other Actions on Google developers.

Using our hypothetical response randomization plugin would look like this:

API Changes

We made several changes to the Client Library API, the most important one being that we’ve split the v1 app object into a global app instance (that represents the app itself) and a per conversation conv instance. This allows you to set cross conversational information, like a debug flag or a default data initiation function, in the app instance, and clearly distinguish per conversation information in the conv instance.

Building on this change, we addressed the feedback about ask and tell being confusing by renaming tell to a more explicit conv.close() to close the mic.

What about ask? ask is still there — in fact, we super powered it :) You can now call ask multiple times, and we will incrementally build the content of the response for you.

More Idiomatic JavaScript

We did a lot of work to make our JavaScript API more idiomatic. My favorite highlight from this work is that in v1 we have classes, builders, and setters/getters for basically everything; in v2, we don’t :)

When, for example, we replace builders and setters with anonymous options objects, we can provide named parameters that make the code much more clear:

TypeScript

Our main focus is to provide a JavaScript API for Actions on Google developers, so don’t worry about switching over to TypeScript!

We did switch from JavaScript to TypeScript as the development language of the client library though. The main reasons is: types!!! Sure, a type system by itself doesn’t make your code correct and all the yadda yadda, but trust us, it makes it much easier to eliminate a lot of problems from the offset and be more productive.

We’re sure that these developers will be very happy about this last change. We’re very thankful for their feedback, and we encourage all of you to provide more!

Next Steps

If you need guidance to migrate your code from v1 to v2, we have published a guide to help you.

If you have any questions, please post them on Stack Overflow or on our Google+ community.