About the Web SDK

Now that you've learned how to configure your Platform Account, you're ready to display your content. This document describes the TwineSocial Web SDK, which is the simplest and quickest way to showcase social content.

Generally, the TwineSocial Web SDK works by providing a line of Javascript that you add to a brand website. This document describes the configuration and display options available for the Web SDK.

(For more advanced brand applications, our Javascript API offers a robust toolset to develop more immersive social experiences.)


Getting Started

To add your TwineSocial campaign to your website, login to your Management Dashboard. Choose your campaign, and choose Publish. You'll see a line of HTML code that you can paste on your website where you'd like campaign content to appear:

<script id="twine-script" src="https://apps.twinesocial.com/embed?app=SPEEDVEGAS&showLoadMore=yes&autoload=no"></script>

This script tag above will display content from the "SPEEDVEGAS" campaign in an IFRAME immediately following the location where you paste this code on your webpage. For example:

Many more advanced features - such as infinite scroll, responsive view, layouts, colors, themes, and CSS are described here.

 More questions? Search the Knowledge Base, or ask in the Community Forums.


Layouts

The TwineSocial Web SDK renders content based on a Layout defined in your Management Dashboard. You can optionally define multiple layouts for your campaigns; each layout can have colors, fonts, theme, locale, CSS, and other attributes associated with it. This is commonly used for brands who need to represent their campaign content differently on different web properties, or who want to embed locale-specific versions of their campaign content as needed.

When displaying your campaign content, the Web SDK uses the configuration settings associated with your default layout, or settings passed in on the script source. (If both are provided, the script source parameters are used.)

Choosing a Layout

You can view, edit, or delete all layouts for a campaign by choosing "Manage Layouts..." while viewing the Design tab for a campaign:

One layout will be defined as the "Default" layout. This layout will be used when the &layout parameter is not provided on the script source. To use a specific layout, add the &layout parameter in the script source:

<script id="twine-script" src="https://apps.twinesocial.com/embed?app=SPEEDVEGAS&layout=18142"></script>

...or, choose the Layout when Publishing your campaign:

 More questions? Search the Knowledge Base, or ask in the Community Forums.


Themes

The TwineSocial Web SDK includes many built-in layout themes, including Gallery, Photo Wall, Tweet Deck, and more. To change the theme used when using the Web SDK, choose, edit, and save your desired theme for a layout while designing your campaign:

...or add the theme-layout parameter to the script source. If a theme-layout is specified in your script source, it will override the theme saved with your Layout.

<script id="twine-script" src="https://apps.twinesocial.com/embed?app=SPEEDVEGAS&theme-layout=gallery"></script>

 More questions? Search the Knowledge Base, or ask in the Community Forums.


Fonts

The TwineSocial Web SDK includes an extensive library of built-in fonts.

Choose a font for your layout by choosing it in the Management Dashboard:

You can also specify a font by including the theme-font parameter in the script source URL:

<script id="twine-script" src="https://apps.twinesocial.com/embed?app=SPEEDVEGAS&theme-font=ubuntu"></script>

If a theme-font is specified in your script source, it will override the theme font saved with your Layout.

Don't see a font you like? Use your own brand font by including it inside your CSS.

 More questions? Search the Knowledge Base, or ask in the Community Forums.


Color Schemes

The TwineSocial Web SDK includes several built-in color schemes suitable for white, dark, and gray websites. To change the theme used when using the Web SDK, edit and save your layout with the specific "Color Scheme" option in the Management Dashboard, or add the theme-color parameter to the script source:

<script id="twine-script" src="https://apps.twinesocial.com/embed?app=SPEEDVEGAS&theme-color=gray"></script>

 More questions? Search the Knowledge Base, or ask in the Community Forums.


Custom CSS

The TwineSocial Web SDK allow you to completely customize the look and feel of rendered content with CSS. To do this, you'll need to upload CSS styles into your layout.

Add your own CSS by choosing the Design tab while viewing a campaign:

Pro Tip: The TwineSocial toolbar provides a rich, real-time preview tool so you can preview your CSS changes in real-time. Access the toolbar in the lower left corner of any page hosting the TwineSocial Web SDK script.

Disabling CSS

While troubleshooting your embedded content, you can temporarily disable any Custom CSS defined in your active layout by adding &css=off to your script source:

<script id="twine-script" src="https://apps.twinesocial.com/embed?app=SPEEDVEGAS&css=off"></script>

 More questions? Search the Knowledge Base, or ask in the Community Forums.


Languages & Locals

By default, your campaign content will be rendered with the Web SDK using UI sharing components in the English language. For example, when your visitors share a piece of content, the English language Facebook, Twitter, Google+ and other sharing components are used. You can specify an alternate language in your layout, or by including the &lang parameter in your script source URL:

<script id="twine-script" src="https://apps.twinesocial.com/embed?app=SPEEDVEGAS&lang=fr"></script>

Support for many common languages are provided. Don't see the language you need? Ask!

 More questions? Search the Knowledge Base, or ask in the Community Forums.


Deep Linking to a Collection

A times you may wish to "deep link" to a collection other than the default collection within your embedded hub. To do this, simply pass in the collection ID in a ?social-collection=YOUR_COLLECTION_ID parameter on the parent page.

https://www.yoursite.com/social_hub/?social-collection=112866

You can include any other parameters (like GA source parameters) along with the social-collection paramater. To find the ID for a collection go to the Collections section in the TwineSocial admin. Then click the gear icon on any collection and copy the Collection ID.

 More questions? Search the Knowledge Base, or ask in the Community Forums.


Advanced Web SDK Options

Additional options can be added to your script source URL. In some cases, these parameters are available as a layout parameter. If the option is included in the layout parameter AND in the script source URL, the script source URL supercedes.

Option Default Values Description
scroll yes yes, no Enable/disable scroll bars on the view. When omitted, the iframe will dynamically be resized to fit the height of your campaign content. This is the preferred implementation, with better support on mobile and tablets. When set to no, your Web SDK content will be in a scrollable region.
pagesize 20 (numeric value)

Maximum number of items to retrieve per request, up to a maximum of 100.

showLoadMore no yes, no Enable/disable infinite scrolling. When set to yes, a Load More button will appear at the bottom of the view. Otherwise, when visitors scroll closer than 400px to the bottom of the document, additional content will be retrieved and appended to the view.
photosOnly no yes Limit display to campaign items that contain a photo.
autoload yes yes, no Auto load more when reading the bottom of the social hub (not the window).
css on off, on If Custom CSS is defined in the layout, setting &css=off will suppress these CSS rules.
height   (numeric) Set the height of the view IFRAME in pixels. Used in combination with scroll=no to constrain the view to a scrollable region.
layout     Use a specific Layout ID when displaying this view.
theme-color white black, white, gray Use a specific theme color when displaying this view.
theme-layout classic classic, display-wall, gallery, sidebar, tweetwall, fullscreen, and others Use a specific theme color when displaying this view. Overrides any layout-specific color.
theme-font open-sans open-sans, architect, courier, dosis, georgia, montserrat, poiret, raleway, times-new-roman, trebuchet, ubuntu, verdana Use a specific font when display this view. Overrides any layout-specific font.
lang en en, fr, it, fr, sv, de, es Use a specific locale/language for the UI components (Facebook sharing, Twitter intents, etc.). Overrides any layout-specific language.
showNav no yes, no Display a navigation element at the top of your view, corresponding to visible Collections.
collection   (numeric) Display content from a specific Collection ID.
debug off on, off Display diagnostic and troubleshooting options in the console window, and throughout the view UI.
extra-class     Add a CSS class name to the body of the view.
displayCTAs yes yes, no

Enable/disable display for CTAs and shoptification links on an embed.

 More questions? Search the Knowledge Base, or ask in the Community Forums.


WordPress Plugin

A WordPress Plugin for TwineSocial is maintained. While the plugin does not offer any additional functionality that cannot be accessed directly with the Web SDK, it may be more convenient for some users. The plugin generates a shortcode for use in a Page or Blog Post, as well as support for Wordpress Widgets.

Learn more about the TwineSocial Wordpress Plugin.

 More questions? Search the Knowledge Base, or ask in the Community Forums.


Broadcast/Projector/TV

A common requirement is to project your campaign content into a broadcast, projector, or TV environment. After choosing a layout, font, theme, and CSS to suit your design requirement, use one of the following hardware solutions:

Solution Notes
HDMI Most laptops offer an HDMI output. Simply embed your layout on a web page, and connect the HDMI output of your laptop to your display device.
Mac Mini: Kiosk Mode Setup a device (such as a Mac Mini) with a kiosk application serving the web page containing your TwineSocial content. Applications that we've worked with include xStand and eCrisper

 More questions? Search the Knowledge Base, or ask in the Community Forums.


Custom Event Tracking

You can access analytics for actions taken on your hubs (such as detail views, shares, and page loads) with Google Analytics or TwineSocial's native analytics. If you need to write analytics to your custom analytics warehouse or to a third-party analytics provider, we recommend you use the onEvent() method.

TwineSDK.onEvent = function(event) {
  // we can now parse the event object and record this event anywhere we like
  console.log(event);
};

The event object contains the following properties:

Property Description
action Specifies the action being taken on the TwineSocial hub. We track the following actions:
  • page_load: A TwineSocial page is loaded.
  • load_more: A user scrolls the page (or clicks the "Load More" button) to load additional posts.
  • view_post: A user clicks the detail modal on a post.
  • share_post: A user shares a post on Facebook from within your hub.
  • tweet_post: A user shares a post on Twitter from within your hub.
  • retweet_post: A user retweets a post on Twitter from within your hub.
  • reply_to_post: A user replies to a post on Twitter from within your hub.
  • favorite_post: A user favorites a post on Twitter from within your hub.
  • pin_post: A user pins a post on Pinterest from within the detail modal.
campaign_name

The name of the TwineSocial campaign on which the action took place.

campaign_base_url

The base URL of the TwineSocial campaign on which the action took place. You can view your campaign at www.twinesocial.com/YOUR_BASE_URL

total_posts

The total number of new posts loaded. Only present on page_load and load_more actions.

network

Specifies the host network of the post being viewed, shared, tweeted, or pinned. Not present on page_load and load_more actions.

post_url

The native URL of the post being viewed, shared, tweeted, or pinned, if available. Not present on page_load and load_more actions.

post_author

The username of the author of the post being viewed, shared, Tweeted, or pinned, if available. Not present on page_load and load_more actions.

 More questions? Search the Knowledge Base, or ask in the Community Forums.