Fair Use

FUMS v3

FUMS is our Fair Use Management System. It's a system that we ask all API developers to use as a way to help us ensure that the API contents are being used fairly. It also allows us to profile usage of the various versions, books, chapters, and verses that are requested from the API, so that we can communicate the value of API-accessible Scripture texts back to copyright holders and publishers. Additionally, we're in progress on a dashboard to communicate these same things back to the consumers of our API. For more information on FUMS, you can read a background on why the it exists in the API Introduction.

To start implementing FUMS in your application, jump down to our walk-through.

What We Collect

In short, we have a privacy focused solution that tracks scripture usage and anonymized user viewing data. At a minimum we only collect three pieces of information, and another if your service has logged in users. Here's what we collect:

FUMS Token

We'll show you how to get a fumsToken in just a moment, but for now this is a value that you'll receive from our servers when you make a request for any scripture content. This is a value that represent the request and allows us to connect your FUMS report to a specific API request.

Device Id

This is a randomly generated id that 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. If you're using JavaScript tracker, this isn't something you'll ever need to worry about. Out of the box, we handle if for you.

Session Id

This also 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. Like the device id, this is something we handle for you if you're using the JavaScript tracker.

User Id (Optional)

If you application doesn't have logged in users, we don't need this value from you. If you application does have logged in users, we ask that you provide the id for the currently active user. This id should never contain any personally identifiable information. However, if you're using our JavaScript tracker, we make sure to obfuscate any value you give us by using the sha256 cryptographic hashing function. This prevents any user information from accidentally being leaked. We use this value to profile scripture engagement at the user level. While the device id allows us to do analytics at the device level, this gives us a better view into how users might be engaging with the scriptures using multiple devices or how multiple users might be sharing a single device.

How Do I Use It?

When making a API request for scripture content, include a query parameter of fums-version=3 to the request url. This will give you access to the latest and easiest way to implement FUMS in your application. Each API response will include a meta key as a child of the initial object. That meta key will contain another key called fumsToken, which contains the value you'll need in order to make a FUMS request.

Here's a request/response listing showing a request for John 3:16 from the KJV.

Request

curl -s -H "api-key: <API-TOKEN>" https://api.scripture.api.bible/v1/bibles/a6aee10bb058511c-02/verses/JHN.3.16\?fums-version\=3

Response

{
  "data": {
    "id": "JHN.3.16",
    "orgId": "JHN.3.16",
    "bookId": "JHN",
    "chapterId": "JHN.3",
    "bibleId": "a6aee10bb058511c-02",
    "reference": "John 3:16",
    "content": "<p class=\"s1\">God So Loved the World</p><p class=\"p\"><span data-number=\"16\" class=\"v\">16</span>For God so loved the world, that he gave his only begotten Son, that whosoever believeth in him should not perish, but have everlasting life. </p>",
    "verseCount": 1,
    "copyright": "King James Version 1611, spelling, punctuation and text formatting modernized by ABS in 1962; typesetting © 2010 American Bible Society.",
    "next": {
      "id": "JHN.3.17",
      "number": "17"
    },
    "previous": {
      "id": "JHN.3.15",
      "number": "15"
    }
  },
  "meta": {
    "fumsToken": "G0wBgBwHbqxlyoOgvZ6lYyp_uvBQFmocvykgSJauvtB528beKuJyHB2OZq8VtIOgO2u2mhHYxiiJ0fzDzeUfz9sB8C_21Fze_TRNl0um2YxiicxzS-KVgtSu1xk5dZwAzX8QIoPp5dJdgAPVxKnEmlM0oCDhj8lYMUM4wCkvEQPBBjxyYVksCbunKC0UV2oZA7Z3ufLztgQ1fftYcvRhYtohRHILNlg9j_ezKk416zSv2p8WcWlDyWTLYjq3S50XSiuaLapg"
  }
}

In the example above, notice the fumsToken that was previously mentioned. When your application makes an API request and displays it on a webpage, it should also always use the fumsToken to report to the FUMS server as well. If your reporting will happen on a webpage, continue reading to learn how to report this value. If you're not in a browser environment, jump to our "How to Report FUMS Manually" section.

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>

This script makes a global function fums available for you to report FUMS. If by chance you've used Google Analytics to do any manual tracking, our library works quite similarly.

The last thing to put is place before reporting FUMS is configuring tracker to anonymously track your logged-in users. If this doesn't apply to your application, skip this step. To update tracker with the current logged-in user's user id run the following command somewhere in your JavaScript:

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

Wonderful! Everything is in its place, at this point the tracker library is loaded, properly configured and we have a fumsToken that we're ready to report. Once you show your user the scripture you will report that view like so using your actual fumsToken. Here's how we'd report the fumsToken from our API response above:

fums(
  "trackView",
  "G0wBgBwHbqxlyoOgvZ6lYyp_uvBQFmocvykgSJauvtB528beKuJyHB2OZq8VtIOgO2u2mhHYxiiJ0fzDzeUfz9sB8C_21Fze_TRNl0um2YxiicxzS-KVgtSu1xk5dZwAzX8QIoPp5dJdgAPVxKnEmlM0oCDhj8lYMUM4wCkvEQPBBjxyYVksCbunKC0UV2oZA7Z3ufLztgQ1fftYcvRhYtohRHILNlg9j_ezKk416zSv2p8WcWlDyWTLYjq3S50XSiuaLapg"
);

In some circumstance you may make multiple calls to our API and have multiple fumsTokens that you want to report at once. To do so, provide an array of fumsTokens to the trackView command like so:

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

In the case that you're needing to report usage for your user listening to an audio bible, we provide a seperate command for that. Unlike trackView, this command only take one fumsToken at a time. Report your usage like so:

fums('trackListen', fumsToken);

That's it! You've implemented FUMS for your application, well done. As your users continue to navigate and are shown more scripture, make sure to continue to report each fumsToken you receive from our servers by calling the trackView command above.

How to Report FUMS Manually

Currently, our client-side tracker is only available for browser-based JavaScript environments. This doesn't cover some cases like some email readers, browsers with JavaScript disabled, and most native applications. If this is you, you'll have to create your FUMS request manually. In most cases, this won't be any more difficult than calling our API.

Here's what a full-fledge FUMS request URL looks like:

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

Let's break down the pieces:

https://fums.api.bible/f3 is the main report url for an invisible single pixel GIF
t is your fumsToken, this is the value received from our API response.
dId is your device Id. This needs to be a constant value for the duration of the device. This should not contain anything personally identifiable for your user, just a unique id for that device.
sId is the session id. This is used to track how multiple views happen in a single session for a single user. This also should be a unique random id.
uId is the user id, optional only if you have logged-in users. This needs to be a constant value representing your user, but nothing personally identifiable. If you'd prefer to obfuscate this value from us, we suggest you hash your actual user id from your database using the sha256 cryptographic hashing algorithm.

When reporting text bibles, you can include multiple fumsTokens in a single request by adding multiple t params like so: t=fumsToken1&t=fumsToken2. In the case you're reporting an audio bible, you must only include a single fumsToken on that report request.

Here's an example of an actual FUMS URL used to report a view:

https://fums.api.bible/f3
  ?dId=aU-xGs0AapCyeJFbZI2Sv
  &sId=hnE8GAmFHgnOkdons4S_7
  &t=G0gBAIzTFfOihHXPwrGlfnnyMm9EbSRIYtI6LF19n94WBcpV1AJswfHCpyt2Ol1uQe2IiPSMHic75R_P2wHgX-zJ-bz7aeFZVqm6UCo0r5bYC3q4-2Fn5BhhvgdCZDC9XLoL4EA1cSqx5hQNQBjwx3Lq2iEDIdgk84HhNkBIyLJYkpFoo9CUXdUyRtjeBZvP2xK4WTupooNPHEdA2hLkAiQarJ7H-1dvwtMVxRztPOWpDRrIllzerFTONcRFDGWJAw

Once you've properly created a FUMS request URL, simple use the HTTP client of your choice in your language to issue a GET request to that URL.

http.Get("https://fums.api.bible/f3?t=fumsToken&dId=deviceId&sId=sessionId&uId=userId")

If you're in a browser environment where JavaScript is disabled, you won't be able to issue this request programmatically. Instead that the url you've created and include it on the page as an image tag when generating the markup server-side:

<img
  src="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. We're looking to make more tracker libraries available in more languages to make this easier to implement in the future. If you think we should make a tracker for your language or if you've created an open-source solution that you'd like to share with our team, reach out to support@api.bible or put in a feature request at https://apibible.canny.io/feature-requests.

Will It Affect Performance?

FUMS has been designed to have no noticeable impact on your site's load time. We have carefully optimized the JavaScript code itself to minimize its size, and we deliver it from a geographically aware content delivery network (CDN). The JavaScript code is lightweight in execution, and will not alter the look or feel of your website in any way.

Documentation Navigation

Table of Contents