Socialcast Learn About Socialcast

Using Metadata

Before a Reach Extension renders on your host page, the Reach script reads the page looking for metadata. By default, Reach can interpret both standard HTML page metadata and the Open Graph Protocol (OGP) schema. If a page contains both types of metadata, Reach uses the OGP metadata first and then the page metadata.

ReachRef_3_message in stream

The image to the right shows how Reach uses the metadata to create a message within the Socialcast community.

Reach uses regular and OGP metadata from the host page to construct the message at the top. The comments below the message are the result of user input on the host page.


HTML Page Metadata

Reach uses the HTML page metadata to create useful messages within the Socialcast community. Be aware that not all of the Reach extensions generate messages. For example, the Trends Extension doesn’t publish content to a community. The following table explains which information Reach pulls from each page.

Message title

The title string will appear as the title of the Socialcast message. Typically, you would pass the name of the application page where the Reach Extension is located. For example,

<title>Benefits: 401K Retirement Plan</title>

Message content

The description string becomes the message content, displayed just below the linked message title. For example,

<meta name="description" content="Employer-sponsored retirement plans are generally grouped into two major categories: defined benefit (DB) and defined contribution (DC).">

Link URL

By default, Reach fetches the URL of the current browser page to use as the link for the message title. You do not need to specify anything.

OGP Metadata

Reach uses the OGP metadata to display Dynamic Extensions and to create messages in the Socialcast community. The Reach parser reads and stores all OGP properties, even if the default Reach interpreter doesn’t use them. If you plan to write you own interpreter, you can use any OGP properties you like.

OGP metadata uses the following format, where the property name is taken from the Open Graph Protocol vocabulary:

<meta property=”og:[property-name]” content=”[value of property]”>
title

This string will appear as the title of the Socialcast message. Typically, you would pass the name of the application page where the Reach Extension is located.

url

This URL is the link for the message title. Generally, the URL would link back to the page where the Reach Extension is located.

description

This string becomes the message content, displayed just below the linked message title.

image

This thumbnail image will appear to the left of the message.

email

To display the profile stream for a particular community member, you can supply that person’s email address.

group_id

To display a particular group stream in a dynamic discussion or stream extension, you can supply the group ID.

group_name

To display a particular group stream in a dynamic discussion or stream extension, you can supply the group name.

Creating a Custom Parser or Interpreter

Reach’s default parser scans the host page and generates a collection of metadata properties that represent the resource. These properties are then mapped to the metadata of Socialcast messages with the default interpreter. When determining the value of a specific property, the parser first looks for any Open Graph Protocol meta tags (og:title, og:description, etc). If no OGP tags are found for a given property, the respective HTML value will be used (<title> tag or META description). For example, if a host page supplies both a meta tag with an og:title property and an HTML <title> tag, the parser will ensure that the value of the og:title property takes priority over the HTML tag. The interpreter will then determine how this value should be used in the representation of a Socialcast message.

Auxiliary Parser

An auxiliary parser allows you to override the default behavior and scan the page for any metadata that is valuable to you. For example, you could define an auxiliary parser that scans for a particular ID on the body element and includes the element’s innerText as a value for document.description:

var AcmeDocumentParser = {
 window: function(win) {
   return { 'uri': win.location.uri };
 },
 body_element: function(element) {
   if (element.getAttribute('id') == 'document_description') {
     return {'document.description': element.innerText };
   }

   if (element.getAttribute('id') == 'document_id') {
     return {'document.id': element.innerText };
   }
   return null;
 }
};

This auxiliary parser can be installed like so:

var _reach = _reach || [];
_reach..push({
 token: ‘123abc’,
 container: ‘socialcast_reach’,
 domain: ‘https://community.socialcast.com’,
 auxiliaryParser: AcmeDocumentParser
};

When the Reach extension begins to load, it will call the window function with the host page’s JavaScript window object and the element function with every XML element in the host page. Both of these methods return maps of property names to values. The window function returns the document’s URL (as seen in the address bar), and the element function returns the contents of specific elements that the integrator knows are present in Acme’s document repository software. Reach understands requests to inspect the following types of objects:

window: The JS Window object element: Every element in the page

Once the properties have been extracted, they are combined into a single collection in preparation for interpretation and passed into the interpreter (default or auxiliary, if defined).

Auxiliary Interpreter

An auxiliary interpreter is a JavaScript function that allows you to inspect and override the metadata that is sent to Socialcast from a host page. If an auxiliary interpreter is provided, it is invoked with two arguments: the set of resourceProperties and messageProperties that were parsed by the default interpreter. resourceProperties is an object that includes all of the raw metadata parsed by the interpreter. messageProperties is an object that maps a subset of the parsed metadata to a Socialcast message. The auxiliaryInterpreter JavaScript function that you supply must return the final object of message properties that will be sent to Socialcast. For example, if you would like to override the message content for a Discussion Extension, you can re-define the value for the message body in an auxiliary interpreter:

var AcmeDocumentInterpreter = function (resourceProperties, messageProperties) {
 messageProperties['body'] = resourceProperties['html.meta.description'] || “This is a message['body'] override!”;
 return messageProperties;
};

and install it like this:

var _reach = _reach || [];
_reach..push({
 token: ‘123abc’,
 container: ‘socialcast_reach’,
 domain: ‘https://community.socialcast.com’,
 auxiliaryInterpreter: AcmeDocumentInterpreter
};

In the above example, any message generated from a Reach Discussion would include either the META tag description (if it exists in the page) or the string This is a message[‘body’] override! The acceptable keys for the messageProperties object are body, image, resource, title, and url. An example of how this example would be represented in Socialcast when a user posts a comment can be seen here:

ReachRef_4_ogp message