Animation: Jump-through

At the time of writing, part of this technique (path morphing) was only supported on Lollipop and newer versions of the OS. Version 25.4 of the Android Support Library however, back-ported this capability all the way back to Ice Cream Sandwich (i.e. an impressive 99% of devices). Check out this Google I/O session covering this and other awesome changes in the Support Library:

I wanted to try out these new capabilities by updating my example to work on older devices and share my findings.

14 is the new 21

The first step was to simply change my minSdkVersion from 21 to 14. Opening up the exact same AnimatedVectorDrawable, the Lint tool pointed out a couple of errors. Specifically I was using some of the standard Material interpolators which were only introduced in API 21 so wouldn’t be available on older platforms. As the Support Library also back-ports PathInterpolators I simply copied their implementations from the platform into my project and referenced these instead.

I also set vectorDrawables.useSupportLibrary = true in my build.gradle file to tell the build toolchain not to strip away vector resources on older devices.

Under construction

To play the animation, you need to get a reference to it in code and call start(). There are multiple ways that you can actually create the animated drawable:

1. Reference it in your layout (app:srcCompat="@drawable/avd_foo") and later retrieve the drawable from the ImageView.
2. Use AppCompatResources#getDrawable
3. Use AnimatedVectorDrawableCompat#create

I found that methods 1 & 2 can return different concrete classes; either an AnimatedVectorDrawable or an AnimatedVectorDrawableCompat depending upon which API you find yourself on.

Interestingly the support library currently uses the native version on API 24+ and the compat version prior despite the class being introduced in API 21. This enables it to supply bug fixes to APIs 21–23.

This can be problematic if/when you need to cast the drawable.

Note that both classes implement Animatable so if all you need is to start/stop it then you can cast away safely. Additionally AnimatedVectorDrawableCompat offers a handy static method to register callbacks, which will check which type we’re dealing with and delegate the callback as appropriate.

Instead I opted for door number 3; always using the compat class. This might add a tiny bit of overhead (as on newer platforms AVDC just delegates everything to the native class) but it made my consuming code simpler.

Call me back

One wrinkle I found was with the technique I used to make the animation loop. Unfortunately AnimatorSets do not support repeating, so I worked around this by adding an AnimationCallback which listens for the end of the animation and calls start again. This did not work on older platforms but I was able to work around it by posting the start call on a handler to be executed after the end callback:

avd?.registerAnimationCallback(
        object : Animatable2Compat.AnimationCallback() {
    override fun onAnimationEnd(drawable: Drawable?) {
        imageView.post { avd.start() }
    }
})

Stale state

Parts of the animation only run at certain points within the loop; for example the dots fade in/out when they enter/exit the scene. On older devices I found that their ‘state’ wasn’t being reset (to how it was defined in the VectorDrawable) on each loop.

Notice how the grey dots are (incorrectly) visible when they enter from the right, then briefly disappear and then fade in. To fix this I added a zero length animation to set properties to their expected value at the start of each loop so that they’re ready to be animated e.g.:

<!-- Fade dot 5 in as it enters the scene -->
<set>
    <objectAnimator
        android:propertyName="fillAlpha"
        android:valueFrom="0"
        android:valueTo="0"
        android:duration="0" />
    <objectAnimator
        android:propertyName="fillAlpha"
        android:valueFrom="0"
        android:valueTo="1"
        android:startOffset="1900"
        android:duration="60"
        android:interpolator="@android:interpolator/linear" />
</set>

Form a queue

The last issue I hit was a problem with sequentially ordered AnimatorSets. The main pin jump animation is a sequence of path morph animations, from keyframe to keyframe. My animation assumed that this sequence would run for the sum of all of the individual animator’s durations. On older platforms however, a bug causes each animator to wait for the next frame boundary before starting. These small delays add up such that the animation took longer than the sum of durations, so other parts of the composition would be mis-timed. I was able to work around this by switching to ordering="together" instead and using startOffsets on each individual animator to start them at the right time.

Impressively unimpressive

The end result is extremely impressive in it’s un-impressiveness. That is, the animation looks exactly the same as before but now runs on many more devices.

Even though I did encounter some issues getting this to work on older devices, they were all pretty easily resolved and I think that the ability to run on so many more API levels makes the effort well worth it.

I was pleased with how many things just worked including the XML bundle format which allows you to specify the VectorDrawable and animations in a single file. Lint tooling was also helpful in pointing out some problems. You can find my code for the back-ported animation here on Github.

If you were holding off adding awesome animations to your application because of lack of API support, then hold-off-no-more. If you’re looking into path-morphing animations then be sure to check out Alex Lockwood’s amazing ShapeShifter tool which will help you to create morph-able shapes. If this has inspired you to create something, then let me know!

Re-animation was originally published in Google Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

In my previous blog post, I talked about how you can use Loaders to load data in a way that automatically handles configuration changes.

With the introduction of Architecture Components, there’s an alternative that provides a modern, flexible, and testable solution to this use case.

Separation of concerns

Two of the largest benefits of Loaders were:

• They encapsulate the process of data loading
• They survive configuration changes, preventing unnecessarily reloading data

With Architecture Components, these two benefits are now handled by two separate classes:

• LiveData provides a lifecycle aware base class for encapsulating loading data
• ViewModels are automatically retained across configuration changes

One significant advantage of this separation is that you can reuse the same LiveData in multiple ViewModels, compose multiple LiveData sources together through a MediatorLiveData, or use them in a Service, avoiding the effort of trying to munge a Loader into a scenario where you don’t have a LoaderManager.

While Loaders espoused a separation between your UI and data loading (one of the first steps to a testable app!), this model expands on that advantage — your ViewModel can be completely tested by mocking out your data sources and the LiveData can be tested in complete isolation. A clean, testable architecture was a large focus in the Guide to App Architecture.

Keep it simple

That all sounds good in theory. An illustrative example recreating our AsyncTaskLoader might help make the ideas a bit more concrete:

public class JsonViewModel extends AndroidViewModel {
  // You probably have something more complicated
  // than just a String. Roll with me
  private final MutableLiveData<List<String>> data =
      new MutableLiveData<List<String>>();

  public JsonViewModel(Application application) {
    super(application);
    loadData();
  }

  public LiveData<List<String>> getData() {
    return data;
  }

  private void loadData() {
    new AsyncTask<Void,Void,List<String>>() {
      @Override
      protected List<String> doInBackground(Void… voids) {
        File jsonFile = new File(getApplication().getFilesDir(),
            "downloaded.json");
        List<String> data = new ArrayList<>();
        // Parse the JSON using the library of your choice
        return data;
      }

      @Override
      protected void onPostExecute(List<String> data) {
        this.data.setValue(data);
      }
    }.execute();
  }
}

Wait, an AsyncTask? How is this safe? There’s two safety features in play here:

1. The AndroidViewModel (a subclass of ViewModel) only has a reference to the application Context, so we’re very importantly not referencing the Context of an Activity, etc. that could present a leak — there’s even a Lint check to avoid these kind of issues.
2. LiveData only delivers the results if there’s something observing it

But we haven’t quite captured the essence of the Architecture Components: our ViewModel is directly building and managing our LiveData.

public class JsonViewModel extends AndroidViewModel {
  private final JsonLiveData data;

  public JsonViewModel(Application application) {
    super(application);
    data = new JsonLiveData(application);
  }

  public LiveData<List<String>> getData() {
    return data;
  }
}

public class JsonLiveData extends LiveData<List<String>> {
  private final Context context;

  public JsonLiveData(Context context) {
    this.context = context;
    loadData();
  }

  private void loadData() {
    new AsyncTask<Void,Void,List<String>>() {
      @Override
      protected List<String> doInBackground(Void… voids) {
        File jsonFile = new File(getApplication().getFilesDir(),
            "downloaded.json");
        List<String> data = new ArrayList<>();
        // Parse the JSON using the library of your choice
        return data;
      }

      @Override
      protected void onPostExecute(List<String> data) {
        setValue(data);
      }
    }.execute();
  }
}

So our ViewModel gets considerably simpler, as you’d expect. Our LiveData now completely encapsulates the loading process, loading the data only once.

Data changes in a LiveData world

Just like how Loaders can react to changes elsewhere, this same functionality is key when working with LiveData — as the name implies, the data is expected to change! We can easily rework our class to continue to load data while there’s an observer:

public class JsonLiveData extends LiveData<List<String>> {
  private final Context context;
  private final FileObserver fileObserver;

public JsonLiveData(Context context) {
    this.context = context;
    String path = new File(context.getFilesDir(),
        "downloaded.json").getPath();
    fileObserver = new FileObserver(path) {
      @Override
      public void onEvent(int event, String path) {
        // The file has changed, so let’s reload the data
        loadData();
      }
    };
    loadData();
  }

  @Override
  protected void onActive() {
    fileObserver.startWatching();
  }

  @Override
  protected void onInactive() {
    fileObserver.stopWatching();
  }

  private void loadData() {
    new AsyncTask<Void,Void,List<String>>() {
      @Override
      protected List<String> doInBackground(Void… voids) {
        File jsonFile = new File(getApplication().getFilesDir(),
            "downloaded.json");
        List<String> data = new ArrayList<>();
        // Parse the JSON using the library of your choice
        return data;
      }

      @Override
      protected void onPostExecute(List<String> data) {
        setValue(data);
      }
    }.execute();
  }
}

Now that we’re interested in listening to changes, we can take advantage of LiveData’s onActive() and onInactive() callbacks to only listen when there’s an active observer on our data — as long as someone is observing, they can be guaranteed to get the latest data.

Observing data

In the Loader world, getting your data to your UI would involve a LoaderManager, calling initLoader() in the right place, and building a LoaderCallbacks. The world is a bit more straightforward in the Architecture Components world.

There’s two things we need to do:

1. Get a reference to our ViewModel
2. Start observing our LiveData

But explaining that is almost as long as the code itself:

public class MyActivity extends AppCompatActivity {
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    JsonViewModel model =
        ViewModelProviders.of(this).get(JsonViewModel.class);
    model.getData().observe(this, data -> {
      // update UI
    });
  }
}

You’ll note there’s no need to clean things up after the fact: ViewModels automatically live only as long as they are needed and LiveData automatically only passes you data when calling Activity/Fragment/LifecycleOwner is started or resumed.

Load all the things

Now, if you’re still in the vehemently-against-AsyncTask camp, I’m totally okay with that: LiveData is a lot more flexible than being tied to only that construct.

For example, Room lets you have observerable queries — database queries that return LiveData so that database changes automatically propagate up through your ViewModel to your UI. Kind of like a CursorLoader without touching Cursors or Loaders.

We can also rewrite the FusedLocationApi example with a LiveData class:

public class LocationLiveData extends LiveData<Location> implements
    GoogleApiClient.ConnectionCallbacks,
    GoogleApiClient.OnConnectionFailedListener,
    LocationListener {
  private GoogleApiClient googleApiClient;

  public LocationLiveData(Context context) {
    googleApiClient =
      new GoogleApiClient.Builder(context, this, this)
      .addApi(LocationServices.API)
      .build();
  }

  @Override
  protected void onActive() {
    // Wait for the GoogleApiClient to be connected
    googleApiClient.connect();
  }

  @Override
  protected void onInactive() {
    if (googleApiClient.isConnected()) {
      LocationServices.FusedLocationApi.removeLocationUpdates(
          googleApiClient, this);
    }
    googleApiClient.disconnect();
  }

  @Override
  public void onConnected(Bundle connectionHint) {
    // Try to immediately find a location
    Location lastLocation = LocationServices.FusedLocationApi
        .getLastLocation(googleApiClient);
    if (lastLocation != null) {
      setValue(lastLocation);
    }

    // Request updates if there’s someone observing
    if (hasActiveObservers()) {
      LocationServices.FusedLocationApi.requestLocationUpdates(
          googleApiClient, new LocationRequest(), this);
    }
  }

  @Override
  public void onLocationChanged(Location location) {
    // Deliver the location changes
    setValue(location);
  }

  @Override
  public void onConnectionSuspended(int cause) {
    // Cry softly, hope it comes back on its own
  }

  @Override
  public void onConnectionFailed(
      @NonNull ConnectionResult connectionResult) {
    // Consider exposing this state as described here:
    // https://d.android.com/topic/libraries/architecture/guide.html#addendum
  }
}

Just scratching the surface of the Architecture Components

There’s a lot more to the Android Architecture Components, so make sure to check out all of the documentation.

I’d personally strongly recommend reading through the entire Guide to App Architecture to give you an idea on how all of these components come together to form a solid architecture for your entire app.

Lifecycle Aware Data Loading with Android Architecture Components was originally published in Google Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

The Developer Show is where you can stay up to date on all the latest Google Developer news, straight from the experts.

Have a question? Use #AskDevShow to let us know!

Advanced Android App Development

The Advanced Android App Development online course has been updated, improved, and extended. With it, you can build a portfolio of apps as you improve your Android dev skills. Check out the the course, linked on the post.

AIY Projects: Do-it-yourself AI for Makers

We recently launched AIY Projects: do-it-yourself artificial intelligence for Makers. With it, makers can use artificial intelligence to make human-to-machine interaction more like human-to-human interactions. We’ll be releasing a series of reference kits, starting with voice recognition. More details and links are on the post.

Chrome 59 Beta

Chrome 59 Beta is now available with Headless Chromium, native notifications on macOS, service worker navigation preload, and more. All the details are on the post.

Google Cloud Launcher adds more container support

Google Cloud Launcher has more Google maintained containers including Cassandra, ElasticSearch, Jenkins, MySQL, and more. Google container solutions are managed by Google engineers and since we’re maintaining the images, the containers available on Google Cloud Launcher will be current with the latest application and security updates.

Google Cloud

There are two announcements from Google Cloud Next London that I wanted to tell you about… First, Google Cloud Natural Language API is adding support for new languages and entity sentiment analysis. And second, Cloud Spanner is now generally available. Check out the details of both announcements on the post.

Google I/O

Google I/O is juuuuust around the corner — and if you’re like me, you like to go in prepared. Which is why we have an Android, iOS, and web app to help you customize your I/O schedule and get around the developer festival. Check out the screenshots and find the download links on the post.

The Developer Show — TL;DR 069 was originally published in Google Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

The Developer Show is where you can stay up to date on all the latest Google Developer news, straight from the experts.

Have a question? Use #AskDevShow to let us know!

Google Assistant SDK

Bring voice control, natural language understanding, Google’s smarts, and more to your devices using the Google Assistant SDK. The developer preview is now available. Get the some sample code and videos from the post.

Structured menus in Google My Business API

Businesses that use the Google My Business API can now publish their entire menu to Google — itemized with descriptions, photos and prices — making it frictionless for their customers to view their menus on Google. Screenshots and sample code are on the post.

Create quizzes in Google Forms with Apps Script

Quizzes in Google Forms help teachers automate testing and give feedback to students faster by having Forms check responses against correct answers automatically. And now you can create these quizzes programmatically with Apps Script. More screenshots and code are on the post.

Next steps toward more connection security

Beginning in October 2017, Chrome will show the “Not secure” warning in two more situations: when users enter data on an HTTP page, and on all HTTP pages visited in Incognito mode. Which makes it a good time for me to say: HTTPS is easier and cheaper than ever before, and it enables both the best performance the web offers and powerful new features that are too sensitive for HTTP. Check out our set-up guides to get started. Everything’s linked from the post.

Manage gRPC APIs with Google Cloud Endpoints

You can define and run a gRPC API and serve both gRPC and JSON-HTTP/1.1 to your clients using Google Cloud Endpoints! More details are on the post.

The Developer Show — TL;DR 068 was originally published in Google Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

jazzy is a command-line utility that generates documentation for Swift or Objective-C. It is composed of two parts:

1. The parser, SourceKitten (written in Swift)
2. The site generator (written in ruby)

It leverages

• modern HTML templating (Mustache)
• the power and accuracy of the Clang AST and SourceKit

In our setup, we have a shell script. It

• simplifies jazzy setup,
• unifies through different modules we have,
• sets mustache templates.

In our first try, we were awed by the beautiful documentation right of the batch. But, we saw couple issues. These were originating because Jazzy was only accepting ObjectiveC/Swift style comments. Whereas Doxygen was supporting C++ style comments. Before diving down to each issue, let me explain how we tackled them:

1. We created a Jazzy style guide for comments for future development.
2. We used Jazzy’s--skip-documentation parameter to find out the missing or broken comments. We integrated this parameter into our script as well for due diligence.
3. We worked with engineers to update the comments into new syntax as soon as we can.
4. In the interim we created a preprocessing script. It removes unsupported keywords from our header files temporarily (just for the execution).

sed -i ‘’ -e ‘s/ * @method [:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/ * @typedef [:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/ * @class [:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/ * @fn [:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/ * @property [:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/ * @enum [:_.[\:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/@abstract //g’ *.h
sed -i ‘’ -e ‘s/@brief //g’ *.h
sed -i ‘’ -e ‘s/@discussion //g’ *.h
sed -i ‘’ -e ‘s/@remarks //g’ *.h
sed -i ‘’ -e ‘s/@returns/Returns/g’ *.h
sed -i ‘’ -e ‘s/ @memberof [:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/ @related[:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/{@link \([:_.[:alnum:]]*[:[:alnum:]]\)}/<code>\1<\/code>/g’ *.h
sed -i ‘’ -e ‘s/@c \([:_.[:alnum:]]*[:[:alnum:]]\)/<code>\1<\/code>/g’ *.h

You can keep reading the Migration Guide from Doxygen to Jazzy.

How to generate fabulous API reference docs for iOS was originally published in Google Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Add comments for all interfaces, protocols, properties, methods, enums, structs, and typedefs

If you don’t have documentation for one of these elements, Jazzy will still include it in the output, marked as “undocumented”. You can use the --skip-documentation parameter with jazzy script to see which declarations in your public headers are missing documentation.

Causes Jazzy Error

@property(nonatomic, copy) NSString *someProperty;

Fix

/// This is a comment for someProperty.
@property(nonatomic, copy) NSString *someProperty;

Alternate Fix

///
@property(nonatomic, copy) NSString *someProperty;

Use documentation tags supported by Jazzy

Jazzy currently only supports the following documentation tags. Do not use @brief, @var, @enum, @protocol, @discussion, or @remarks as they are not currently supported by jazzy. To see the formatting for Quick Help in Xcode, press and hold the “option” key and click on the method name or property.

1. @see
2. @param
3. @return
4. <code></code creates a link to a constant, property, or method and should be used instead of @link (use <code></code with @see)
5. <pre> instead of \code or @code
6. </pre> instead of \endcode or @endcode

Fix

/// This is the description for a method.
///
/// @see <code>someProperty</code>
/// @see <code>-someMethod:</code>
///
/// <pre>
/// // This is a comment inside a code snippet.
/// // @code and @endcode are not currently supported by
/// // jazzy. Use <pre> and </pre> instead.
/// NSString *someString = [[NSString alloc] init];
/// </pre>
///

/// @param someParam1 This is a description for someParam1.
/// @param someParam2 This is a description for someParam2.
///
/// @return Description of the return value.
(NSString *)someMethodWithParam1:(NSString *)someParam1 
                          param2:(NSString *)someParam2;

Alternate Fix

/**
 * This is the description for a method.
 *
 * @see <code>someProperty</code>
 * @see <code>-someMethod:</code>
 *
 * <pre>
 * // This is a comment inside a code snippet.
 * // @code and @endcode are not currently supported by
 * // jazzy. Use <pre> and </pre> instead.
 * NSString *someString = [[NSString alloc] init];
 * </pre>
 *
 * @param someParam1 This is a description for someParam1.
 * @param someParam2 This is a description for someParam2.
 *
 * @return Description of the return value.
 */
(NSString *)someMethodWithParam1:(NSString *)someParam1
                          param2:(NSString *)someParam2;

Add blank lines before and after the @param block

There needs to be a newline between the last description paragraph and the first parameter block. There also needs to be a newline before the @return block. Otherwise the parameters and return value show up in both the description (badly formatted).

Causes Jazzy Error

/**
 * Use removeObserverWithHandle: to stop receiving updates.
 * @param eventType The type of event to listen for.
 * @param block The block that should be called with initial data.
 * @return A handle used to unregister this block later.
 */

Fix

/**
 * Use removeObserverWithHandle: to stop receiving updates.
 *
 * @param eventType The type of event to listen for.
 * @param block The block that should be called with initial data.
 *
 * @return A handle used to unregister this block later.
 */

Use #pragma mark instead of @name

Do not use @name tags, they show up with the */ characters appended to the end in the Jazzy built files. Use #pragma mark instead.

Causes Jazzy Error

/** @name Attach observers to read data */

Fix

#pragma mark — Attach observers to read data

Use + instead of * in Markdown lists

Do not use * Markdown syntax to create bulleted lists, they won’t show up as lists and the * characters are left behind, making things look like pointers.

Causes Jazzy Error

/**
 * To modify the data, set its value property to any of the native
 * types support by Firebase Database:
 * * NSNumber (includes BOOL)
 * * NSDictionary
 * * NSArray
 * * NSString
 * * nil / NSNull to remove the data
 */

Fix

/**
 * To modify the data, set its value property to any of the native
 * types support by Firebase Database:
 *
 * + NSNumber (includes BOOL)
 * + NSDictionary
 * + NSArray
 * + NSString
 * + nil / NSNull to remove the data
 */

Use HTML syntax for error-code lists

If you don’t, Jazzy puts them all together on one line. Also need a — character between the error code name and the description.

Causes Jazzy Error

@remarks Possible error codes:
- @c FIRAuthErrorCodeInvalidCustomToken Indicates a validation error with the custom token.
- @c FIRAuthErrorCodeCustomTokenMismatch Indicates the service account and the API key belong to different projects.

Fix

@remarks Possible error codes:
<ul>
  <li>@c FIRAuthErrorCodeInvalidCustomToken — Indicates a validation error with the custom token.</li>
  <li>@c FIRAuthErrorCodeCustomTokenMismatch — Indicates the service account and the API key belong to different projects.</li>
</ul>

Note: the <ul> must not have an empty line between it and the line above or it will end up in a separate <p> tag and not show bullets.

No @c tags inside @param or @return tags

They break the build.

Causes Jazzy Error

@param app The @c FIRApp for which to retrieve the associated @c FIRAuth instance.
@return The @c FIRAuth instance associated with the given @c FIRApp.

Fix

@param app The FIRApp for which to retrieve the associated FIRAuth instance.
@return The FIRAuth instance associated with the given FIRApp.

No smart quotes (“”)

They get passed through by Jazzy and cause warnings when you add the generated docs to a CL.

Causes Jazzy Error

“One account per email address”

Fix

"One account per email address"

Use nullable and nonnull in Objective-C public headers

Audit Objective-C public headers with nullability annotations for interoperability with Swift code. Simple pointers that can be nil in Objective-C should be annotated as nullable so that they are mapped properly to optional types in Swift.

Causes Swift to map everything to implicitly unwrapped optional

- (AAPLListItem *)itemWithName:(NSString *)name;

Fix

- (nullable AAPLListItem *)itemWithName:(nonnull NSString *)name;

For more information, see Nullability and Objective-C in the Apple Developer Blog.

Hide documentation for private/pre-release properties and methods with :nodoc:

Properties and methods sometimes make it into header files before you’re ready to document them. To skip documenting these properties or methods, add :nodoc: to their comment, like so:

/**
 * A new authorization token that we’re not ready to document yet.
 * :nodoc:
 */
@property(nonatomic, copy) NSString *authToken;

How to migrate iOS API Reference from Doxygen to Jazzy was originally published in Google Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

In the past few months, I heard someone smart saying that “the future is artificial intelligence first”.

Artificial intelligence, is making computers “smart” so they can think on their own and be even more helpful for us. It’s clear that Google, has been investing heavily in the areas of:

• Machine learning — Teaching computers how to see patterns in data and act on it.
• Speech recognition and Language understanding — Meaning, being able to understand you when you are talking with all the little differences and nuance.

These days we can see it all come together in the Google Assistant. It allows you to have a conversation with Google and be more productive. In this post, we will see how it’s all working by building a new Action for Google home. In the same time, we will have a nice bot that in the future we will integrate with other services (e.g. Slack).
Cool?

What?

Google Home is a voice activated speaker that users keep in their home. The Google Assistant is the conversation between the users and Google. They can get things done by talking with the Assistant. There are many things users can do by just using the Assistant directly. To learn more about the assistant check out this short video below.

Actions on Google allows developers to extend the assistant. That is what we are going to focus on today in our animal joke example. This post will walk you through creating your own Action on Google with API.AI.

We are going to use API.AI which is a conversational user experience platform, or in other words, it will help us ‘talk’ to machines in a way they will understand us better.

Let’s start from the end. Please click on the image below and play with our bot to see what is going on. You can start with something like: “please tell me a joke about a dog”

How does a conversation action works?

The user needs to invoke your action. You say a phrase like “Ok Google, talk to Animal joke”. This tells Google the name of the action to talk to.

From this point onwards, the user is now talking to your conversation action. Your action generates dialog output, which then spoken to the user. The user then makes requests, your action processes it, and replies back again. The user has a two way dialog until the conversation is finished.

See below, if you like diagrams to ‘see’ what we explained above.

What is API.AI?

API.AI let’s the machine understand what the user is trying to say, and can provide response. You type in example sentences of things that a user might speak.

You can specify what values you need to get from the user. It then uses machine learning to understand the sentences and manage the conversation.

Click the following link to login to API.AI.

After the login you can create your first agent. You will need to:

1. Give your agent a name.
   In our case, it will be “AnimalJoker”. Please note that the agent name can not contain any spaces between the words.
2. Give a short description so other users will know what this action is going to do.
   In our case, type: “An action that tells animal jokes. But only the good ones”.
3. Click on ‘Save’.
   It’s the button in the top-right corner of the screen.

What are entities?

Entities are the values we are trying to capture from the user phrases. Kind of like filling out a form, requesting details from the user. API.AI looks to extract these out, and will do follow up prompts until done. This is how an entity looks in API.AI

We will create an Animal entity.

First step is to click on the ‘Create Entity’ button (it’s at the top-right corner).

Next you should start typing animals’ names.

The final results should look similar to the image below.

Things to remember:

1. You should ‘help’ API.AI machine learning algorithm to train itself by providing synonyms. For example, dog could also be puppy. In our case, you can give it only 2–3 animals. That will be fine for now.
2. In the real world, try to give many examples so it will cover more cases.

What is an intent?

An Intent is triggered by a series of “user says” phrases. This could be something like “please tell me an animal joke” or “Give me a recipe for burger”.

You need to specify enough sentences to train API.AI’s machine learning algorithm. Then even if the user doesn’t say exactly the words you typed here, API.AI can still understand them!

You should create separate intents for different types of actions though.

Don’t try to combine all of them together.

In our example, we will create only two intents:

• Tell_Joke intent — This intent will handle the jokes.
• Quit intent — This intent will handle the part when the user wish to finish the action.

Build the “Tell_Joke” intent

After we have our new $Animal entity. If you notice the $ before the word — It’s not a mistake. This is the way we will refer to our new entity from now. Think of it as a special sign to show us that we are referring to our entity and not just another animal.

It’s time to create the intent that will tell us the jokes.

First, click on the ‘Create Intent’ button.

Second, start typing few sentences that you will want to use to get a joke. For example, “please tell me a joke on dogs”. Type a few sentences so API.AI could start training its algorithms. You can see that while you type, API.AI automatically recognizes that the phrase includes one of the entities, so it highlights it.

See below how it should look like.

Next, we are skipping the ‘events’ part, and in the ‘Action’ section we need to make sure that our @Animal entity is required and in the “user says” input line, we should type “Please tell me which animal you like” so in cases where the user didn’t name an animal, it will be clear to her that we need this entity.

Finally, in the ‘Text Response’ section we are filling our most amazing jokes. You can take few ideas from the image below.

Please note that we are using the $Animal value in our response in order to create a joke that is based on the animal that the user asked.

After you fill all your amazing jokes, don’t forget to click on the ‘save’ button on the top-right corner of the screen.

Build the “Quit” intent

A good design principle is to allow our user to end the conversation.

You should click again on ‘Create Intent’ button. Than, start typing few sentences that will end the conversation. For example, “bye bye” or “bye animal joker”.

Below is how this intent should look like.

Last, but not least, you need to check the ‘end conversation’ checkbox so that it will know to really end the conversation at this point.

We are almost done!

Btw, if you wish to load all these definition without following this tutorial step by step, you can do it with 3 simple steps.

See the image below.

Once you import everything from the zip file, you can start to add or edit more intent and entities.

Testing

Click on ‘Integrations’ in the right side menu. This will open the Agent page with all the options to integrate it with other services (e.g. chat apps, twitter etc’).

You have two easy and quick ways to test your creation. one is to follow the link that you see under ‘Agent Page’. But don’t forget to set the ‘Publish’ switch before you click on the link to your new bot.

Another way is to click on “Actions on Google” box under “One-click integration”. This will enable you to test your work as it will be running on Google Home.

Once you click on ‘Actions on Google’ you will see this dialog:

Fill the invocation name and click on ‘Preview’ button.

You will get a screen that let’s you talk with the simulator. See the image below.

The cool aspect of the web simulator is that it will give you all the answers both in english as text/sounds and on the right side, the full JSON object.

Best Practices

• There are some policies about what a Conversation Action can be named and support.
• Only Conversation Actions, with a well defined invocation, are supported. Meaning, the trigger sentence should be clear and short.
• The guidelines explain all the rules around them.

In the next post I’ll we will go a bit deeper with webhooks and the ability to use your own engines in order to provide answer with useful information.

Be strong and build amazing actions!

Originally published on Ido Green

Build Your First Smart Bot For Google Home was originally published in Google Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Recently @ToddKerpelman and I converted a reference iOS Google Cast app to Swift. Before, I implemented Firebase iOS quickstarts. I created both ObjectiveC and Swift target at the same time. But I never tried to migrate a full app to Swift before. So I welcomed this challenge.

Blame me being lazy. I didn’t want to do to mundane work of declaring each variable and function in Swift. I decided to take a leap in faith and try a converter tool as a starter. I was going to see how good it can translate. Then I was going to catch build errors and bugs after checking line by line. Finally I was going through with a linter tool to catch any bad style.

After googling “ObjectiveC to Swift converter” I decided to give a try to Swiftify. I did a test on a small file, it looked good. Then I uploaded the whole project, pressed convert button, closed my eyes and hoped for the best.

What I received looked like a Swift code. There were double definitions of the variables as they got imported from both .h and .m. Some of the definitions that should’ve been on the top of the file were on the bottom. But in general it looked like I saved tons of hours of mundane work to fix dots and parentheses. Because of the original code, I even saw definitions like private(set) public var. We started with 269 build errors (more like 800 as you fix, you get more :). Luckily there were lots of low hanging fruits:

• double definitions of vars
• wrong optionality, function signatures
• Swift 3 style issues (enumeration naming)
• Xcode suggested fixes (nullability checks).

This took 3 days as we go down all the way to 2 digits. Now the no-brainer bugs were gone. We had to use assistant view to fix remaining bugs side by side. Most of the bugs turned out to be wrong guesses on the optionality types of class vars. Converter always picks implicitly unwrapped variables instead of optionals. Or it would try to guess local variable types wrong. (You don’t need to declare variable types most of the times as Swift can infer them). Only because I was eager to see the app built, I took a shortcut. I used force unwrapping and force casting only to get rid of build errors. Little did I know, I was going to pay a high price for this later on debugging. After bunch of var to let conversions (converter defined all variables as var), we had an app that built!

Don’t get so hyped yet, we were only beginning. Yes, our app was building, but returning no data and crashing at startup. We spent the next 100 hours debugging to find all the

• null errors
• wrong if not null checks,
• and lots of optionality fixes.

After those, our app was initializing. It was “almost” casting, yet another force unwrapping error.

There is a reason for style guides. They help you to use the language the way it was designed to be used, and they prevent most bugs before you create them. At that moment SwiftLint came to rescue. You can run SwiftLint on Xcode to see all the style guide exceptions on the lines they occur, and fix them quick. I was determined to get rid of all optionality bugs and stay close to style guide as much as possible. I enabled even the opt-in rules. Fixing style not only helped the readability, but also improved our confidence on the errors. We found further bugs on the way. We got rid of all the force unwrapping, force casting, explicit type declarations, implicitly unwrapped optionals. We favored if let and guard let statements wherever possible.

Results:

We will be refactoring the app in next weeks, but at least, we have a 1-to-1 swift port of the CastVideos sample app now.

1. Swiftify saved us valuable time instead of converting the project line by line. (As long as you now it’s not going to do the all work for you. It’ll be a guesstimate)
2. Never ever use ! (unwrapping symbol) unless you have no other choice. Force unwrapping myVar!, force casting as!, implicitly unwrapped optionals Type! are very prone to errors.
3. Replacing them with if let, guard let, and optional chaining x?.y?.do() will recover your app from exceptions instead of crashing and will help you in debugging.
4. Style guides both improves readability and make your code less prone to bugs. SwiftLint was a great tool to force the Swift style guide.

How to Convert a full ObjectiveC app to Swift was originally published in Google Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Actions on Google lets you add audio to actions, which gives dimension to dialogs and a sense of atmosphere to the overall user experience.

<SPEAK>

To play audio as part dialogs, actions support the Speech Synthesis Markup Language (SSML), a standard markup language for the generation of synthetic speech.

To use the SSML markup, start by wrapping your prompts inside <speak> tags:

<speak>Welcome to Number Genie!</speak>

Then use other SSML tags to add sounds and control the audio rendering. For example, to play an audio file:

<speak><audio src="https://.../meow.ogg"></audio></speak>

Since SSML is based on XML, special characters need to use XML escaping:

<speak>&quot;What have I learned?&quot; he asked.</speak>

Take a Break

When designing a conversational flow, don’t just consider the words but also the pace of the dialog. This is especially important when you have a design that calls for something more wordy.

For our Interactive Fiction actions, we added SSML <break> tags between the sentences to better pace the story telling:

<speak>Grunk think that pig probably go this way.<break time="800ms"/>It hard to tell at night time, because moon not bright as sun.<break time="800ms"/>There forest to east and north.</speak>

An important aspect of our conversational design principles is to test your dialogs before you implement them, to get a feel for how they’ll sound for end users. Try reading them out loud to your colleagues, or use our web simulator. Keep tweaking the SSML markup values until you have the pacing just right.

The Cow Says Moooooo

Sound effects (SFX) are a very easy way to raise the production value of your action, especially when you implement games.

In our Number Genie action, we use sounds to give users fun feedback to let them know how well they are doing during the game:

• A cold wind sound when the guess is very far from the answer,
• A steam sound when the user is within 3 of the answer,
• A steam sound with bells when the user is even closer,
• A congratulatory sound when the user guesses the answer.

But where can you get sounds for your action? Well, the YouTube audio library provides over 5,000 free sounds that you can use in your own projects. We’ve picked our favorite short sounds for the actions sound library and hosted them for you on Google’s servers so you can reference them in your actions:

<speak>
<audio  
  src="https://actions.google.com/sounds/v1/alarms/alarm_clock.ogg">
</audio>
</speak>

P-R-O-N-U-N-C-I-A-T-I-O-N

In addition to supporting audio playback, SSML also lets you have more fine-grained control over how your prompts are pronounced, making your action’s responses seem more life-like and appropriate for the kind of information provided to the user.

In particular, when you have to say numbers or dates, you can specify how you want to want the data to be interpreted. For example, if you want to say “12345” as “Twelve thousand three hundred forty five”:

<speak><say-as interpret-as="cardinal">12345</say-as></speak>

Other interpretations for numbers, characters, dates, times and telephone numbers are also supported.

Let’s Play

Now we can bring this all together by designing our own trivia game action. We’ll be using many of the SSML features to create the mood and SFX of a typical game show.

For our persona we want a game show host so we pick the voice, “male 2”, from our list of voices available for actions.

Now, design the greeting for users of the action:

<speak>
<audio src="https://.../game_intro.ogg"/>
Let’s play the SSML Trivia Game!
Put on your game face.
Here comes your first question.
<break time="500ms"/>
Which one of these is the world’s tallest waterfall?
<break time="500ms"/>
Angel Falls
<break time="500ms"/>
Victoria Falls
<break time="500ms"/>
Or Niagara Falls
<audio src="https://.../ding.ogg"/>
</speak>

Note the use of the ‘ding’ sound to make it clear to the user that the question is complete and it’s the users turn. This is an example of an earcon (think ‘icon’ for ears) which are distinct sounds that provide feedback or convey additional information.

Once the user provides an answer, the action can further recreate the ambiance expected for a typical game-show with an audience-reaction sound:

<speak>
<audio src="https://.../audience_reaction_correct.ogg"/>
You called it. Great job!
Here’s the next question.
...
</speak>

If you are using API.AI to develop your action, then you can use SSML in the text responses when creating an intent:

Or if you use fulfillment to dynamically generate the responses in code, then you can use SSML with the Node.js client library “ask” or “tell” methods:

assistant.tell('<speak>OK. See you next time!
   <audio src="https://.../bye_sound.ogg"/></speak>');

Make sure you wrap the <speak> tags around the entire string, and not just a subset of it.

Next Steps

I’ll leave it to you to design the rest of the game show dialogs. Start with the happy path and keep adding support for other typical user interactions. Use sound to delight and entertain your users!

After you have confirmed your action meets the guidelines in the Actions on Google design checklist, submit your action so that everybody can enjoy your fun action.

Thanks to Nandini Stocker, Google’s Conversation Design Lead, for co-authoring this post.

SSML for Actions on Google was originally published in Google Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

1. Install Docker
2. Install Travis on Docker

# choose the image according to the language chosen in .travis.yml
$ docker run -it -u travis quay.io/travisci/travis-jvm /bin/bash

# now that you are in the docker image, switch to the travis user
sudo — travis

# Install a recent ruby (default is 1.9.3)
rvm install 2.3.0
rvm use 2.3.0

# Install travis-build to generate a .sh out of .travis.yml
cd builds \
git clone https://github.com/travis-ci/travis-build.git \
cd travis-build \
gem install travis \
travis # to create ~/.travis \
ln -s `pwd` ~/.travis/travis-build \
bundle install

# Create ssh key for Github
ssh-keygen -t rsa -b 4096 -C “YOUR EMAIL REGISTERED IN GITHUB”

# Click enter to use default location for key
# You can choose empty passphrase by clicking enter twice

# Now that we have the key, let’s share with Github
less ~/.ssh/id_rsa.pub

# Copy the contents of the id_rsa.pub

3. Go to your Github SSH key settings
4. Create a new ssh key with title: “docker key”: “PASTE THE KEY CONTENTS HERE”
5. Go back to docker terminal

# Create project dir, assuming your project is `AUTHOR/PROJECT` on GitHub
cd ~/builds \
mkdir AUTHOR \
cd AUTHOR \
git clone git@github.com:AUTHOR/PROJECT.git \
cd PROJECT

# change to the branch or commit you want to investigate
# compile travis script into bash script
travis compile > ci.sh

# Go to bash script and fix the branch name
vi ci.sh

# in Vi type “/branch” to search and add the right branch name
# — branch\=\’\NEW_BRANCH’\

# You most likely will need to edit ci.sh as it ignores ‘matrix’ and ‘env’ keywords
bash ci.sh

Congrats, in few steps you are already running TravisCI locally.

How to Run TravisCI locally on Docker was originally published in Google Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.