Bitmoji Picker

Hello Bitmoji

138 |

139 |

` endpoint. The popular stickers are in a pack called `popular` so the endpoint is `https://bitmoji.api.snapchat.com/direct/pack/popular`. To authenticate the user, you need to pass the token in the `Authorization` header. 148 | 149 | ```html 150 | 165 | ``` 166 | 167 | The `data` field contains the payload. Each sticker has a `uri` property with an image URL. That's all it is needed to render the content. 168 | 169 | ### Displaying the content 170 | 171 | With the information from the previous step you can easily display all the stickers with adding this code to the function 172 | 173 | ```js 174 | const stickerPicker = document.getElementById('stickers'); 175 | stickers.forEach(sticker => { 176 | const image = new Image(100, 100); 177 | image.src = sticker.uri; 178 | stickerPicker.appendChild(image); 179 | }); 180 | ``` 181 | 182 | > Note: This is an extremely inneficient way of displaying the data. We are focused on the minimal code that you can then adapt to your own libraries and frameworks. 183 | 184 | With this code you should now see a lot of stickers featuring your avatar 185 | 186 | ## Providing Search functionality 187 | 188 | ### Adding controls 189 | 190 | With a text input and a button is easy to implement a basic search UI. Update the sticker-picker div to 191 | 192 | ```html 193 |

194 | 198 |

199 |

200 | ``` 201 | 202 | Bitmoji Direct provides search functionality through the `https://bitmoji.api.snapchat.com/direct/search?q=YOUR_SEARCH_TERM` endpoint. To authenticate the user, you need to pass the token in the `Authorization` header. 203 | 204 | You can add the following code after the sticker loading code to provide basic search functionality 205 | 206 | ```js 207 | const searchBox = document.getElementById('search-box'); 208 | searchBox.style.display = 'block'; 209 | const searchButton = document.getElementById('search-button'); 210 | 211 | searchButton.addEventListener('click', async (e) => { 212 | e.preventDefault(); 213 | const searchText = document.getElementById('searchbox').value; 214 | const response = await fetch(`${HOST}/direct/search?q=${searchText}`, { 215 | headers: { 216 | Authorization: `Bearer ${token}` 217 | } 218 | }); 219 | const json = await response.json(); 220 | const stickers = json.data; 221 | 222 | stickerPicker.childNodes.forEach(node => node.remove()) 223 | stickers.forEach(sticker => { 224 | const image = new Image(100, 100); 225 | image.src = sticker.uri; 226 | stickerPicker.appendChild(image); 227 | }); 228 | }); 229 | ``` 230 | 231 | If you type `hello` in the search box and hit enter the content should be replaced with stickers matching your search term. 232 | 233 | ### Clean up the code 234 | 235 | After our last step there is a significant amount of duplication. You can simplify significantly refactoring to 236 | 237 | ```js 238 | const HOST = 'https://bitmoji.api.snapchat.com'; 239 | 240 | async function fetchFromAPI(url, token) { 241 | const response = await fetch(url, { 242 | headers: { 243 | Authorization: `Bearer ${token}` 244 | } 245 | }); 246 | const json = await response.json(); 247 | return json.data; 248 | } 249 | 250 | function getPopularStickers(token) { 251 | return fetchFromAPI(`${HOST}/direct/pack/popular`, token); 252 | } 253 | 254 | function getStickerSearchResults(token, searchText) { 255 | return fetchFromAPI(`${HOST}/direct/search?q=${searchText}`, token); 256 | } 257 | 258 | function renderStickers(stickers) { 259 | const stickerPicker = document.getElementById('stickers'); 260 | stickerPicker.innerHTML = ''; 261 | stickers.forEach(sticker => { 262 | const image = new Image(100, 100); 263 | image.src = sticker.uri; 264 | stickerPicker.appendChild(image); 265 | }); 266 | } 267 | 268 | async function loadBitmojiContent(token) { 269 | const stickers = await getPopularStickers(token); 270 | renderStickers(stickers); 271 | 272 | const searchBox = document.getElementById('search-box'); 273 | searchBox.style.display = 'block'; 274 | 275 | const searchButton = document.getElementById('search-button'); 276 | searchButton.addEventListener('click', async (e) => { 277 | e.preventDefault(); 278 | const searchText = document.getElementById('searchbox').value; 279 | const searchResultStickers = await getStickerSearchResults(token, searchText); 280 | renderStickers(searchResultStickers); 281 | }); 282 | } 283 | ``` 284 | 285 | ## Providing pack browsing functionality 286 | 287 | ### Showing available packs 288 | 289 | Bitmoji Direct also groups content in a set of packs. In a similar fashion to `popular`, you can get stickers grouped by a given tag such as `yes`, `hello` or `happy`. To get a set of tags you can suggest to your users you can call the `https://bitmoji.api.snapchat.com/direct/packs` endpoint. 290 | 291 | Update the sticker `div` to 292 | 293 | ```html 294 |

295 | 299 |

300 |

301 |

302 | ``` 303 | 304 | and now load the packs into `

` with 305 | 306 | ```js 307 | 308 | (...) 309 | 310 | function getPacks(token) { 311 | return fetchFromAPI(`${HOST}/direct/packs`, token); 312 | } 313 | 314 | (... in loadBitmojiContent) 315 | const packs = await getPacks(token); 316 | const tagsContainer = document.getElementById('tags'); 317 | packs.forEach(pack => { 318 | const packLink = document.createElement('a'); 319 | packLink.innerHTML = pack.name; 320 | packLink.style.marginRight = '24px'; 321 | packLink.href = "#"; 322 | tagsContainer.appendChild(packLink); 323 | }); 324 | ``` 325 | 326 | ### Showing stickers within pack when clicking 327 | 328 | Now you can add the event handler to show the relevant content when clicking one of the tags. To do so, the `id` field within the pack is used. `popular` is just another pack `id` field. Let's refactor `getPopularSticker` to accept any packId 329 | 330 | ```js 331 | function getPackStickers(token, packId) { 332 | return fetchFromAPI(`${HOST}/direct/pack/${packId}`, token); 333 | } 334 | 335 | (... in loadBitmojiContent) 336 | const stickers = await getPackStickers(token, 'popular'); 337 | ``` 338 | 339 | Finally, let's add the click handler for the tags 340 | 341 | ```js 342 | packLink.addEventListener('click', async (e) => { 343 | e.preventDefault(); 344 | const stickers = await getPackStickers(token, pack.id); 345 | renderStickers(stickers); 346 | }); 347 | ``` 348 | 349 | ## Picking a sticker 350 | 351 | When users select a sticker an action like should happen. For instance, you may want to share the sticker in a 1:1 conversation in a chat application. To do this the same URI used to display the sticker preview may be used. 352 | 353 | Let's update the app UI to include an area to display the selected image 354 | ```html 355 |

356 |

357 | 361 |

362 |

363 |

364 |

365 | 366 |

367 |

368 | 369 | ``` 370 | 371 | Now in the function where we render the stickers, we can add a handler to call a function with the click event is triggered: 372 | ```js 373 | function renderStickers(stickers) { 374 | const stickerPicker = document.getElementById('stickers'); 375 | stickerPicker.innerHTML = ''; 376 | stickers.forEach(sticker => { 377 | const image = new Image(100, 100); 378 | image.src = sticker.uri; 379 | image.onclick = () => shareSticker(sticker); 380 | stickerPicker.appendChild(image); 381 | }); 382 | } 383 | 384 | function shareSticker(sticker) { 385 | document.getElementById('share-area').src = sticker.uri; 386 | } 387 | ``` 388 | 389 | If you test this code it will work, but the shared image will apear pixelated. To allow faster loading times in your picker, stickers are loaded on their `thumbnail` size. This may be undesirable for the sharing use case where a higher image resolution may be required. It is trivial to do this. Stickers have a number of query parameters attached to them, you can manipulate the `size` parameter to load a bigger size image. The available options are: 390 | - `default`: 400x400 pixels 391 | - `large`: 800x800 pixels 392 | 393 | Adding the size parameter to the example: 394 | ```js 395 | function shareSticker(sticker) { 396 | document.getElementById('share-area').src = sticker.uri.replace('size=thumbnail', 'size=default'); 397 | } 398 | ``` 399 | 400 | Bitmoji may be notified that a sticker has been picked to share. A stub example could be: 401 | 402 | ```js 403 | function shareSticker(sticker) { 404 | document.getElementById('share-area').src = sticker.uri.replace('size=thumbnail', 'size=default'); 405 | fetch(`${HOST}/direct/event/${sticker.on_share}`, { method: 'post' }); 406 | } 407 | ``` 408 | 409 | ## Customizing content 410 | 411 | ### Locale 412 | The `/packs`, `/pack/{packId}` and `/search` endpoints support a `locale` query parameter. The content will be returned in the locale of your choice if supported. I will default to English. 413 | 414 | The locales supported currently are: `en`, `ar`, `de`, `es`, `fr`, `it`, `ja`, `ko` and `pt`. 415 | 416 | If you don't provide an explicit `locale` parameter but the `accept-language` HTTP header is set, the API will resolve based on the header. 417 | 418 | ### Time 419 | The `/packs` and `/pack/{packId}` endpoints support a `time` parameter. 420 | 421 | Bitmoji content is variable depending on time of day. To be able to display the right content to your users you can send a date string in the `time` query parameter and timely content will be returned if available. 422 | 423 | Example of valid time strings are `2020-10-15T13:05:05`(no timezone) or `2020-10-15T18:02:04-04:00`(with timezone). 424 | 425 | ### Pagination 426 | 427 | The `/pack/{packId}` and `/search` endpoints support optional `limit` and `page` query parameters to paginate through the returned data. `limit` 428 | should be a positive integer while `page` should be 0 or positive. If only a `limit` param is passed, the `page` defaults to 0. Specifying only 429 | `page` doesn't affect the results. 430 | 431 | To help with pagination, the result from Bitmoji direct API also returns metadata in the JSON result, this can be ignored if you aren't using 432 | pagination. This includes the field `next` - URL path with query pointing to the next page, `prev` URL path with query pointing to the previous 433 | page and `total` - the total number of elements for this query (this can be used to set the page size). `next` and `prev` are null if 434 | pagination params weren't specified or if no `next` or `prev` page exists. Note that `next` and `prev` preserve original query params. 435 | 436 | As an example, the result for `https://bitmoji.api.snapchat.com/direct/search?q=hi&locale=en&limit=10&page=2` is as follows: 437 | 438 | ```json 439 | { 440 | "data": [...], 441 | "metadata": { 442 | "next": "/direct/search?q=hi&locale=en&limit=10&page=3", 443 | "prev": "/direct/search?q=hi&locale=en&limit=10&page=1", 444 | "total": 56 445 | } 446 | } 447 | ``` 448 | 449 | ## Full code for reference 450 | 451 | ```html 452 | 453 | 454 | 455 | 456 | 457 | Bitmoji Picker 458 | 459 | 460 | 461 |

462 |

463 | 467 |

468 |

469 |

470 |

471 | 472 |

473 |

474 | 475 | 511 | 512 | 584 | 585 | 586 | 587 | 588 | ``` 589 | -------------------------------------------------------------------------------- /docs/vanilla-sticker-picker/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | Bitmoji Picker 7 | 8 | 9 | 10 |

11 |

12 | 16 |

17 |

18 |

19 |

20 | 21 |

22 |

23 | 24 | 60 | 61 | 133 | 134 | 135 | 136 | -------------------------------------------------------------------------------- /images/bfd_logo_black.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Bitmoji/BitmojiForDevelopers/3d0d0d166b9f5e8f64bc1ac9fee683d974456b31/images/bfd_logo_black.png -------------------------------------------------------------------------------- /images/bfd_logo_green.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Bitmoji/BitmojiForDevelopers/3d0d0d166b9f5e8f64bc1ac9fee683d974456b31/images/bfd_logo_green.png -------------------------------------------------------------------------------- /images/bfd_logo_white.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Bitmoji/BitmojiForDevelopers/3d0d0d166b9f5e8f64bc1ac9fee683d974456b31/images/bfd_logo_white.png --------------------------------------------------------------------------------