Integrating with MashedIn

If you are a developer that has a set of users with public pages, you can integrate with MashedIn to add a MashedIn widget to all of their pages. In order to do this, you need to ask us for two pieces of information:

  • a Partner ID (pid), and
  • a Secret Key.

Please contact us to obtain this information.

There are two integration points for this type of integration:

  • the Widgets, and
  • the Settings Page (optional).

There are two widgets to choose from: a Mutual Connections widget and a Recommendation widget. See below for details on each.

Tip: When in development and testing, use the host sandbox.mashedin.com. For your production deployment, use www.mashedin.com.

These two hosts do not share any data, so work on the sandbox will not impact the production server. Your Partner ID and Secret Key are the same for both environments.

Integrating the Widget

A widget is placed on the public page(s) of the user. To add the widget, you need to include a piece of HTML on each page, dynamically inserting the appropriate user ID.

There are two widgets to choose from: a Mutual Connections widget and a Recommendation widget.

Mutual Connections Widget

The Mutual Connections widget is ideal for showing visitors to a website or blog how they are socially connected to the owner of the website or blog, e.g., if the visitor and owner have common friends. For the Mutual Connections widget to work, you will also need to integrate the Settings Page.

For the Mutual Connections widget, the HTML to add to your pages is as follows:

where:

pid
This is your Partner ID, e.g., XZ .
uid
This is your user's ID. This is a string that identifies the user in your system and matches the uid from the Settings Page url below.

Recommendation Widget

The Recommendation widget is ideal for collecting recommendations and comments from visitors. This widget allows visitors to identify themselves by authenticating with major social networks and then recommending the owner (i.e., the user identified by the context where the widget is mounted).

For the Recommendation widget, the HTML to add to your pages is as follows:

where:

pid
This is your Partner ID, e.g., XZ .
uid
This is your user's ID. This is a string that identifies the user in your system.

Styling the Widgets

The various colors on the widget can be specified using the following request parameters on the widget urls (i.e., http://www.mashedin.com/widget/w1/{pid}/{uid} for Mutual Connections widget, http://www.mashedin.com/widget/w2/{pid}/{uid} for Recommendation widget):

  • background-base,
  • background-primary,
  • border,
  • background-secondary,
  • font,
  • font-secondary,
  • img-border-sm,
  • img-border-lg,
  • link, and
  • heading.
The value of the parameter is the 3 or 6 character hex color.

For example, for the Mutual Connections widget, to set the background-primary to red, use the following widget url:

http://www.mashedin.com/widget/w1/{pid}/{uid}?background-primary=FF0000

Tip: background-base is useful for the Mutual Connections widget to get the rounded corners looking great on sites with a non-white background.

Integrating the Settings Page

The Settings Page is where your users configure the Mutual Connections widget for use. To integrate this page, you need to create a new page behind your authentication that frames in our Settings Page. This allows you to keep your look and feel and navigation; the Settings Page will look like a page on your site.

To do this, simply create an iframe as follows. You'll need to sign the url; see below for more information.

where:

pid
This is your Partner ID, e.g., XZ .
uid
This is your user's ID. This is a string that identifies the user in your system.
signature
This is the computed signature, created by using your Secret Key. Note the signature is not your actual Secret Key and you should never put your Secret Key on any request to our system. See below for specifics on generating this signature.
expiration
This is the POSIX expiration time of this iframe request. After this time has passed, any requests for this url will result in a 403 Forbidden. This means that you should regenerate the expiration and signature each time the user navigates to this iframe. If you regenerate the expiration, a typical expiration is 30 seconds in the future.

Important! When we receive a request on this signed url, we will assume that you have already authenticated your user and we automatically log them in to our system. It is important that this signed url only be accessible to a user that is authenticated to your system.

Signing the Settings Page iframe URL

Signing the Settings Page iframe url allows us to verify that you are sending a specific user to our system so that we can automatically log them in. To sign this url, you need to construct a string like the following:

where:

http_verb
This value will be GET (uppercase).
expires
The POSIX expiration time for this request, must match the exp value in the Settings Page url.
host
This value will be sandbox.mashedin.com or www.mashedin.com .
resource
This value will be /settings/s1/{pid}/{uid} , with your pid and your user's uid substituted.

Once you have this string assembled, you can compute the signature according to RFC2104. We use SHA-1 as the cryptographic hash function.

In Python, the signature can be computed as follows:

where:

secret
This is your Secret Key that you obtained from mashedin.com.
Tip: Signing urls can be tricky. You can test your signing algorithm by hitting the url http://sandbox.mashedin.com/api/test-signature/{pid}?sig={signature}&exp={expiration} . The resource (for the string_to_sign) in this case is /api/test-signature/{pid} .