summaryrefslogtreecommitdiff
path: root/docs/html/training/safebrowsing/index.jd
blob: c6c72bfd1460a120668640cea0a857b2d2eb7bc1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
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>
&lt;application&gt;

    ...

   &lt;!-- SafetyNet API metadata --&gt;
   &lt;meta-data android:name="com.google.android.safetynet.API_KEY"
   android:value="<var>your-API-key</var>" /&gt;

    ...

&lt;/application&gt;
</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&lt;SafetyNetApi.SafeBrowsingResult&gt;() {

    &#64;Override
    public void onResult(SafetyNetApi.SafeBrowsingResult result) {
        Status status = result.getStatus();
        if ((status != null) &amp;&amp; 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>