API.Bible Logo
MenuClose Menu

Documentation Navigation

Fair Use

Table of Contents

Overview

Note: if you only use API.Bible for your mobile app (i.e. an app you download from the Apple App Store of Google Play Store and has no user-accessible web functionality) you can skip this section.

FUMS is our Fair Use Management System that we require all API developers to use in web apps. It allows us to profile usage of the various versions, books, chapters, and verses that are requested from the API so that we can communicate thoroughly with copyright holders and publishers.

What We Collect

  • FUMS Token: This represents your request when you make a call for Scripture. It comes back in the response and allows us to connect your FUMS report to a specific API request.
  • Device ID: This randomly generated ID is an anonymous representation of one specific device and is used for the lifetime of that device. This allows us to track usage at the device level. We handle this for you via the Javascript tracker.
  • Session ID This is a randomly generated id that is regenerated at the start of every session. It allows us to do analytics on how people engage with the scriptures in a given sitting. We also handle this for you via the Javascript tracker.
  • User ID (Optional): If your application has logged in users, we ask that you provide the ID for the currently active user. This ID should never contain any PII. Our Javascript tracker automatically obfuscates any value you give us by using the sha256 cryptographic hashing function. We use this to profile scripture engagement at the user level.

Finding your FUMS Token

All responses for Scripture content contain a meta key with a fumsToken inside it. Capturing this will enable you to make a FUMS request:

Request

curl -s -H "api-key: <API-TOKEN>" https://v2.api.bible/bibles/a6aee10bb058511c-02/verses/JHN.3.16

Response

{
  "data": {...},
  "meta": {
    "fumsToken": "G0wBgBwHbqxlyoOgvZ6lYyp_uvBQFmocvykgSJauvtB528beKuJyHB2OZq8VtIOgO2u2mhHYxiiJ0fzDzeUfz9sB8C_21Fze_TRNl0um2YxiicxzS-KVgtSu1xk5dZwAzX8QIoPp5dJdgAPVxKnEmlM0oCDhj8lYMUM4wCkvEQPBBjxyYVksCbunKC0UV2oZA7Z3ufLztgQ1fftYcvRhYtohRHILNlg9j_ezKk416zSv2p8WcWlDyWTLYjq3S50XSiuaLapg"
  }
}

How to Report FUMS in a JavaScript Environment

The simplest way to report FUMS is using our JavaScript tracker. The first step is to include the tracker on your website. Paste this script tags anywhere in your HTML document, we suggest somewhere near the footer of your document.

<script
  type="text/javascript"
  src="https://pkg.api.bible/fumsV3.min.js"
></script>
<script>
  /* This code ensures that FUMS will be reported correctly even if fumsV3.min.js has not finished loading before an attempt is made. */
  window.fumsData = window.fumsData || [];
  window.fums =
    window.fums ||
    function () {
      window.fumsData.push(arguments);
    };
</script>

With this script present, you now have access to a new function: fums(). If you have logged-in users, you can pass in the userId of the current user session as a config param in fums(), like this:

fums("config", { userId: "your-users-id" });

Now, you should be all set to report the fumsToken you received in your scripture request. To do that, call your fums() function:

fums("trackView", fumsToken);

If you have made multiple calls to the API and want to report each fumsToken in one go, you can pass an array of fumsTokens:

fums('trackView', [fumsToken1, fumsToken2, ...]);

For audio Bibles, there is a separate param you'll want to use:

fums("trackListen", fumsToken);

How to Report FUMS Manually

If your product is not accessed via a browser, reporting FUMS manually is certainly possible:

https://fums.api.bible/f3?t=fumsToken&dId=deviceId&sId=sessionId&uId=userId

Params

t: fumsToken. You can pass as many t params as you need (ie: &t=fumsToken1&t=fumsToken2).

dId: deviceId

sId: sessionId

uId: userId

Here is an example GET command to submit this tracking:

fetch(
  `https://fums.api.bible/f3?t=${fumsToken}&dId=${deviceId}&sId=${sessionId}&uId=${userId}`,
);

If you're finding this too complicated to implement, or have questions about how to do so in your specific situation, don't hesitate to reach out to our support.

Will It Affect Performance?

It will not. The Javascript is quite lightweight, and we deliver it from a geographically-aware CDN.

Prev

Scripture Styling