cherry-pick from nyc-dev: docs: SafeBrowsing API

    path_attributes:

    - name: description

      value: How to use the SafetyNet service to analyze a device where your app is running and get information about its compatibility with your app.

  - title: Checking URLs with the Safe Browsing API

    path: /training/safebrowsing/index.html

    path_attributes:

    - name: description

      value: How to use the SafetyNet service to determine if a URL is designated as a known threat.

  - title: Enhancing Security with Device Management Policies

    path: /work/device-management-policy.html

    path_attributes:

page.title=Checking URLs with the Safe Browsing API

@jd:body

<div id="tb-wrapper">

  <div id="tb">

    <h2>

      In this document

    </h2>

    <ol>

      <li>

        <a href="#tos">Terms of Service</a>

      </li>

      <li>

        <a href="#api-key">Requesting and Registering an Android API Key</a>

        <ol>

          <li>

            <a href="#manifest">Adding the Android API to your

            AndroidManifest.xml</a>

          </li>

        </ol>

      </li>

      <li>

        <a href="#connect-google-play">Connect to Google Play Services</a>

      </li>

      <li>

        <a href="#url-check">Requesting a URL Check</a>

        <ol>

          <li>

            <a href="#threat-types">Specifying threat types of interest</a>

          </li>

          <li>

            <a href="#url-check-request">Send the URL check request</a>

          </li>

          <li>

            <a href="#url-check-response">Read the URL check response</a>

          </li>

        </ol>

      </li>

      <li>

        <a href="#warning-lang">Suggested Warning Language</a>

      </li>

    </ol>

  </div>

</div>

<p>

  SafetyNet provides services for determining whether a URL has been marked as

  a known threat by Google.

</p>

<p>

  The service provides an API your app can use to determine whether a

  particular URL has been classified by Google as a known threat. Internally,

  SafetyNet implements a client for the Safe Browsing Network Protocol v4

  developed by Google. Both the client code and the v4 network protocol were

  designed to preserve users' privacy, as well as keep battery and bandwidth

  consumption to a minimum. This API allows you to take full advantage of

  Google's Safe Browsing service on Android in the most resource-optimized way,

  and without having to implement its network protocol.

</p>

<p>

  This document shows you how to use SafetyNet for checking a URL for threat

  types of interest.

</p>

<h2 id="tos">

  Terms of Service

</h2>

<p>

  By using the Safe Browsing API, you consent to be bound by the <a href=

  "https://developers.google.com/safe-browsing/terms">Terms of Service</a>.

  Please read and understand all applicable terms and policies before accessing

  the Safe Browsing API.

</p>

<h2 id="api-key">

  Requesting and Registering an Android API Key

</h2>

<p>

  To create an API key, complete the following steps:

</p>

<ol>

  <li>Go to the <a href="https://console.developers.google.com/project"

    class="external-link">Google Developers Console</a>.

  </li>

  <li>On the upper toolbar, choose <strong>Select a project &gt;

  <em>your-project-name</em></strong>.

  </li>

  <li>In the search box, enter <em>Safe Browsing APIs</em>; when the Safe

  Browsing API name appears in the table, select it.

  </li>

  <li>After the page redisplays, select <strong>Enable</strong> then select

  <strong>Go to Credentials</strong>.

  </li>

  <li>When the <em>Add credentials to your project</em> window appears, choose

  your parameters then select <strong>What credentials do I need?</strong>.

  </li>

  <li>Enter a name for your API key then select <strong>Create API

  key</strong>.

  </li>

  <li>

    <p>

      Your new API key appears; copy and paste this key for future use.

    </p>

    <p class="note">

      <strong>Note:</strong> Your API key allows you to perform a URL check

      10,000 times each day. The key, in this instance, should just be a

      hexadecimal string, not part of a URL.

    </p>

  </li>

  <li>Select <strong>Done</strong> to complete the process.

  </li>

</ol>

<p>

  If you need more help, check out the <a href=

  "https://developers.google.com/console/help/new/">Google Developers Console

  Help Center</a>.

</p>

<h3 id="manifest">

  Adding the Android API key to your AndroidManifest.xml

</h3>

<p>

  Once your key has been whitelisted, you need to add the key to the

  <code>AndroidManifest.xml</code> file for your app:

</p>

<pre>

<application>

    ...

   <!-- SafetyNet API metadata -->

   <meta-data android:name="com.google.android.safetynet.API_KEY"

   android:value="<var>your-API-key</var>" /&gt;

    ...

</application>

</pre>

<h2 id="connect-google-play">

  Connect to Google Play Services

</h2>

<p>

  The SafetyNet API is part of Google Play services. To connect to the API, you

  need to create an instance of the Google Play services API client. For

  details about using the client in your app, see <a href=

  "https://developers.google.com/android/guides/api-client#Starting">Accessing

  Google APIs</a>. Once you have established a connection to Google Play

  services, you can use the Google API client classes to connect to the

  SafetyNet API.

</p>

<p>

  To connect to the API, in your activity's <code><a href=

  "{@docRoot}reference/android/app/Activity.html#onCreate(android.os.Bundle)">onCreate()</a></code>

  method, create an instance of Google API Client using <code><a href=

  "https://developers.google.com/android/reference/com/google/android/gms/common/api/GoogleApiClient.Builder">

  GoogleApiClient.Builder</a></code>. Use the builder to add the SafetyNet API,

  as shown in the following code example:

</p>

<pre>

protected synchronized void buildGoogleApiClient() {

    mGoogleApiClient = new GoogleApiClient.Builder(this)

            .addApi(SafetyNet.API)

            .addConnectionCallbacks(myMainActivity.this)

            .build();

}

</pre>

<p class="note">

  <strong>Note:</strong> You can only call these methods after your app has

  established a connection to Google Play services by receiving the <code>

  <a href="https://developers.google.com/android/reference/com/google/android/gms/common/api/GoogleApiClient.ConnectionCallbacks#public-methods">

  onConnected()</a></code> callback. For details about listening for a completed

  client connection, see <a href=

  "https://developers.google.com/android/guides/api-client#Starting">Accessing

  Google APIs</a>.

</p>

<h2 id="url-check">

  Requesting a URL Check

</h2>

<p>

  A URL check allows your app to determine if a URL has been marked as a threat

  of interest. Some threat types may not be of interest to your particular

  app, and the API allows you to choose which threat types are important for

  your needs. You can specify multiple threat types of interest.

</p>

<h3 id="threat-types">

  Specifying threat types of interest

</h3>

<p>

  The constants in the {@code SafeBrowsingThreat} class contain the

  currently-supported threat types:

</p>

<pre>

package com.google.android.gms.safetynet;

public class SafeBrowsingThreat {

  /**

   * This threat type identifies URLs of pages that are flagged as containing potentially

   * harmful applications.

   */

  public static final int TYPE_POTENTIALLY_HARMFUL_APPLICATION = 4;

  /**

   * This threat type identifies URLs of pages that are flagged as containing social

   * engineering threats.

   */

  public static final int TYPE_SOCIAL_ENGINEERING = 5;

}

</pre>

<p>

  When using the API, you must use constants that are not marked as deprecated.

  You add threat type constants as arguments to the API. You may add as many

  threat type constants as is required for your app.

</p>

<h3 id="url-check-request">

  Send the URL check request

</h3>

<p>

  The API is agnostic to the scheme used, so you can pass the URL with or

  without a scheme. For example, either

</p>

<pre>

String url = "https://www.google.com";

</pre>

<p>

  or

</p>

<pre>

String url = "www.google.com";

</pre>

<p>

  is valid.

</p>

<pre>

SafetyNet.SafetyNetApi.lookupUri(mGoogleApiClient, url,

       SafeBrowsingThreat.TYPE_POTENTIALLY_HARMFUL_APPLICATION,

       SafeBrowsingThreat.TYPE_SOCIAL_ENGINEERING)

               .setResultCallback(

                       new ResultCallback<SafetyNetApi.SafeBrowsingResult>() {

    @Override

    public void onResult(SafetyNetApi.SafeBrowsingResult result) {

        Status status = result.getStatus();

        if ((status != null) && status.isSuccess()) {

            // Indicates communication with the service was successful.

            // Identify any detected threats.

            if (result.getDetectedThreats().isEmpty()) {

            }

        } else {

            // An error occurred. Let the user proceed without warning.

        }

    }

});

</pre>

<h3 id="url-check-response">

  Read the URL check response

</h3>

<p>

  The result is provided as a list of {@code SafeBrowsingThreat} objects by

  calling the {@code SafetyNetApi.SafeBrowsingResult.getDetectedThreats()}

  method of the returned {@code SafetyNetApi.SafeBrowsingResult} object. If the

  list is empty, no threats were detected; otherwise, calling {@code

  SafeBrowsingThreat.getThreatType()} on each element in the list enumerates

  the threats that were detected.

</p>

<h2 id="warning-lang">

  Suggested Warning Language

</h2>

<p>

  Please see the Safe Browsing API Developer's Guide for <a href=

  "https://developers.google.com/safe-browsing/v4/usage-limits#suggested--warning-language">

  suggested warning language</a>.

</p>

 No newline at end of file