Share Service

Use the share service to allow users to share content from your application into Symphony conversation:

// To use the share service, you must subscribe to it from your application
var shareService = SYMPHONY.services.subscribe("share");

When the share function is invoked, a modal dialog is launched and populated with the shared object content (for example, the article options). The end user can then select conversations (IMs or chatrooms) into which to share the article.

Once the article is shared, it appears in the conversation view in a card format. The article will be linked either to a webpage (if the href option is provided) or deep linked into the app (if the id option is provided).

In order to view article contents in an application (for example, if the article id is provided), the user must have the application installed.

If the recipient of a shared article does not have the application installed, the user will be prompted to install the application (provided that the user's enterprise has that application enabled).

If the recipient of a shared article does not have the application installed, and the application is not enabled for the user's enterprise, the user can view the content via the link (if href is provided). If a link is not provided, the user will be notified that the article cannot be viewed because the application is disabled for the enterprise.

The following methods are available on the share service:

share()

Launches the "Share on Symphony" modal from your application, allowing the user to share content from your application into a Symphony conversation (IM or chatroom):

function share(type, content, options)

Parameter

Type

Required

Description

type

String

Yes

The type of content that is being shared.

content

Object

Yes

An object that describes the content being shared. For a list of objects see standard entities.

options

Object

No

An object that describes options that can be used to enhance the share service

The following JavaScript shows an example of an article being shared:

// This code will live in your application view.

// Assume there is a button element with id "share" on the application module
// If that button is clicked, launch the Share modal.

var shareButton = document.getElementById("share");

var articleContent = {
  title: "Symphony Launches Mobile App",
  subTitle: "Application is mobile device management (MDM) compatible.",
  blurb: "Symphony Communication Services, a Palo Alto, Calif.-based messaging startup, announced its enterprise-ready mobile app for Apple iPhone is now available for download.",
  date : new Date("07 June 2016").getTime() / 1000,
  publisher: "Waters Technology",
  author: "Dan DeFrancesco",
  id: "symphony-article",
  thumbnail: 'https://symphony.com/example/image.png',
  href: 'https://symphony.com'
};

var shareOptions = {
  prepopulateUsers: ['71811853190920', '71811853190903']
};

// Launch Symphony's share modal when the Share button is clicked
shareButton.addEventListener("click", function(){
  shareService.share(
    "article",
    articleContent,
    shareOptions
  );
});

The following table shows the article content:

Field

Required

Format

Description

title

Yes

String

The headline of the article

subTitle

No

String

The subtitle of the article

blurb

No

String

A summary of the article to display

date

No

Date of publication

publisher

No

String

Name of the publisher

author

No

String

Name of the author

thumbnail

No

URL (could be a data url)

Image to be displayed - 106px-106px

id

Must provide either id or href, or both

String

An identifier used by the application to deeplink to the article

href

Must provide either id or href, or both

URL

URL to the article (opened in a new browser window)

The following table shows the share options:

Field

Required

Format

Description

prepopulateUsers

No

Array of strings

The users (UserIds) who will be listed initially as recipients in the share modal.

Available only for authenticated apps, and only for Client 2.0.

It is recommended to limit the number of pre-populated users so the Symphony end user can easily review the list of recipients before sharing.

Sharing Third Party Content

The share function can also be used to share custom, third-party entity types. In this case, the data parameter must be populated with the following fields:

Field

Description

inputAutofill

Use this to fill the comment field in the share dialog to provide initial text. Cash tags and hash tags that are specified in the text will be converted to the correct entity.

plaintext

The markdown representation of the entity, supporting a limited set of markdown features. The value of this field will be displayed on mobile devices and other older clients.

presentationML

The default presentation of the entity using presentationML. This will be seen by everybody who does not have an app with a custom renderer for the given type.

entityJSON

The object being shared.

format

The format of the message being sent. This must be set to "com.symphony.messageml.v2".

The following JavaScript shows an example of a custom third party entity being shared:

share : function(gameNbr, time)
{
    var fullTime = time;
    var hours = Math.floor(time / 60 / 60 / 1000);
    time -= hours * 60 * 60 * 1000;
    var minutes = Math.floor(time / 60 / 1000);
    time -= minutes * 60 * 1000;
    var seconds = Math.floor(time / 1000);
    var duration = hours.toString() + ':' + minutes.toString().pad(2, '0', 'left') + ':' + seconds.toString().pad(2, '0', 'left');

    var title = 'Somebody you know won at Mah Jongg Solitaire';
    var blurb = 'try to beat their time of ' + duration;
    var date = new Date().getTime() / 1000;
    var thumbnail = this.thumb;
    var id = JSON.stringify({gameNbr: gameNbr, time: fullTime});

    var presentationML =`
        <entity>
            <table><tr>
                <td><img src="${thumbnail}" /></td>
                <td>
                    <h1>${title}</h1>
                    ${blurb}
                </td>
            </tr></table>
        </entity>`;

    var entityJSON = {
        date: date,
        thumbnail: thumbnail,
        results: id,
        time : time,
        gameNbr : gameNbr,
    };

    var data = {
        plaintext: `*${title}*\n${blurb}\n`,
        presentationML : presentationML,
        entityJSON: entityJSON,
        entity: {},
        format: 'com.symphony.messageml.v2',
        inputAutofill : 'I ROCK!',
    }
    this.shareService.share('com.symfuny.invite.won', data);
}

In this example, the following modal dialog is launched and populated with the shared object content:

You must specify your own application service for handling clicks on shared articles using handleLink if you use the id field for deep linking articles into your application.

You must implement the link method on your application service in order to handle clicks on shared articles in conversations.

// This code will live in your application controller.

// The application service that will be used to handle clicks on shared articles
var helloControllerService = SYMPHONY.services.register("hello:controller");

// Assume you have registered your application with the Symphony client and subscribed to the Share service.

shareService.handleLink("article", "hello:controller");

helloControllerService.implement({
    // You only need to implement this function if you intend to deeplink articles into your app by specifying an id for the article. If you use href, then article links will open in a new browser window.
  link: function(type, articleId) {
    if(type == "article") {
      // Implement this
      // For example, you might launch a new application module with a url that includes the articleId in the query parameters
      console.log("Article with id: " + articleId + " was clicked.");
    }    
  }
});

Last updated