Funeral Recording Webcasting API

This API is for Funeral Recording partners. It lets you integrate webcasting into your websites.

The API has two points of integration. The first is a "Schedule Webcast" link, for use of the funeral home employee. The second is the ability to embed the webcast into the obituary, or link to it.

The integration should be stateless on your side; there is no need to add fields to your database for tracking the state of each webcast.

Schedule Webcast Link

Before the funeral, the funeral home employee (hereafter called the "user") should schedule the webcast. This lets her send email invitations to family members.

In order to webcast a funeral, the user will need to have some hardware set up at her location. If a user clicks the "Schedule Webcast" link and is not yet set up, they will be given instructions on how to contact us about getting the hardware.

The link looks something like this:

<a target="_blank" href="http://api.funeralvue.com/webcast?partner_id=test4096&user_id=1234&funeral_id=4123&auth=199dad8aee7536f061e0e73ca2c8cafa">
  Schedule Webcast
</a>

Required parameters are described as follows:

partner_id: Unique identifier we'll assign you.
user_id: Unique alphanumeric identifier for each funeral home. You provide this. It can be whatever you want, as long as it is distinct for each funeral home.
funeral_id: Unique alphanumeric identifier for the webcast. You provide this. It can be whatever you want, as long as it is distinct for each funeral.
auth: Equal to HEX(MD5(partner_secret + MD5(partner_secret + user_id + "," + funeral_id). This stops curious users from changing the user_id or funeral_id parameters of the link and thereby create or modify webcasts belonging to someone else. We will give you the partner_secret. Note that the result should be lowercase hexadecimal.

Sample code for calculating auth in PHP:

$message = "$user_id,$funeral_id";
$auth = md5($secret . md5($secret . $message, true));

In Ruby:

require 'digest/md5'
message = "#{user_id},#{funeral_id}"
auth = Digest::MD5.hexdigest(secret + Digest::MD5.digest(secret + message))

When the user clicks the link, she will be provided with a form asking for more information. If you already have access to the information, you can prefill the form by using the following optional fields:

name: A UTF-8 string, the name of the deceased. Make sure to URL-encode this parameter.
dob: Date the deceased was born, in "YYYY-MM-DD" format.
dod: Date the deceased became deceased, in "YYYY-MM-DD" format.
date: Date of the funeral. Format is "YYYY-MM-DD".
time: Time of the funeral. Format is "HH:MM", in 24-hour time.

Embedding in Obituary

The second optional point of integration is the ability to embed the webcast into the obituary. By having the webcast embedded, it makes it easy for friends and family to find the webcast. The user can control whether or not the webcast is password protected.

If an obituary doesn't have a webcast associated with it, nothing will be embedded in the obituary. This makes it possible for you to add the code on all obituaries, without needing to determine whether or not a webcast is present for that particular one. The embed is loaded asynchronously, meaning that it won't slow down the page. If you'd like to do additional actions based on whether or not a webcast is available, javascript callbacks are available.

Embedding on a page requires a placeholder div tag, with an ID of your choosing. The webcast, if it exists, will be placed inside the div, and a CSS class of webcast-present will be added to the div. (This allows you to style the box differently depending on whether or not the webcast exists.)

<div id="funeral-recording-webcast"></div>

The webcast video player is 512 pixels wide and 524 pixels tall.

Some javascript is needed in order to initialize the webcast. This can be placed anywhere on the page above or below the placeholder div. The partnerID, userID, and funeralID parameters should match what was used earlier, for the "Create Webcast" link.

<script type="text/javascript">
  FuneralRecordingWebcast = {
    partnerID: "test4096",
    userID: "1234",
    funeralID: "4123",
    target: "funeral-recording-webcast" // ID of placeholder div
  };
</script>
<script src="http://api.funeralvue.com/webcast-embed.js" async="async"></script>

In addition to the parameters listed, the following callback parameters are accepted:

onAvailable: Called if the webcast exists and was successfully inserted in the page.
onAbsent: Called if no webcast exists.
onFailure: Called if there was a problem loading the webcast.

For example:

FuneralRecordingWebcast = {
  partnerID: "test4096",
  userID: "1234",
  funeralID: "4123",
  target: "funeral-recording-webcast",
  onAvailable: function() {
    jQuery('#funeral-recording-webcast').css('border', '10px solid orange');
  },
  onFailure: function(message) {
    alert( "Cannot find webcast: " + message );
  }
};

Link in Obituary

Instead of embedding the webcast within the obituary, a link to a separate page can be used instead. This is done using the same javascript API as above:

<script type="text/javascript">
  FuneralRecordingWebcast = {
    partnerID: "test4096",
    userID: "1234",
    funeralID: "4123",
    target: "funeral-recording-webcast", // ID of placeholder div
    link: true
  };
</script>
<script src="http://api.funeralvue.com/webcast-embed.js" async="async"></script>

This will insert an A tag into the target div. You can use the onAvailable callback to customize it, or use the following options for common customizations:

text: Override the link text.

openNewWindow: Have the link open in a new window.

For example:

<script type="text/javascript">
  FuneralRecordingWebcast = {
    partnerID: "test4096",
    userID: "1234",
    funeralID: "4123",
    target: "funeral-recording-webcast", // ID of placeholder div
    link: {
      text: "Watch Funeral LIVE",
      openNewWindow: true
    }
  };
</script>
<script src="http://api.funeralvue.com/webcast-embed.js" async="async"></script>

To style the link with CSS, target the 'webcast-present' class. For example:

/* Style link like a button */

#funeral-recording-webcast.webcast-present a {
  background: #39d;
  background-image: linear-gradient(to bottom #39d #28b);
  border-radius: 14px;
  color: white;
  font-size: 20px;
  text-decoration: none;
  padding: 10px 20px 10px 20px;
}

Test Data

To make development easier, we have created the following test values:

partner_id: Set this to "test4096".

user_id: If partner_id is set to "test4096", set user_id to "1234" to see how the "Schedule Webcast" link behaves when the user is already set up. Set it to anything else to see the content that explains to the user how to get the hardware necessary to webcast.

funeral_id: If partner_id is set to "test4096" and user_id is set to "1234", funeral "4123" will have a webcast that you can embed on a test obituary. Any other funeral ID should show you the behavior when there isn't a webcast scheduled, i.e. the embed should do nothing.

partner_secret: The "test4096" partner has a secret of 5fc34b57972d0d7c0c63defa8ebb1da0. For the user "1234" and funeral "4123", that gives an auth value of 199dad8aee7536f061e0e73ca2c8cafa.

Contact

Send questions to webcasting-api@tukios.com. We are also available via phone, 801-682-4391.