The New Polaris WC

Polaris is built using the latest web technology primitive, Custom Elements, which you can learn more about in an article by Eric Bidelman. By utilizing Custom Elements, we've made the implementation of the new Polaris much simpler for third parties to implement without an iframe and with a total payload under 20kb. As browsers implement customElements natively the new Polaris will become even faster. Currently Chrome and Safari 10.1 have customElements v1 implemented with Firefox actively developing. If you need more information or want to contribute to the project, reach out to us in slack #polaris.

Browser Support

Polaris supports IE11, Chrome, Edge, Safari, Firefox, Opera mobile Chrome and mobile Safari. Support typically includes the lastest two releases of a browser, as the newest browsers auto update.

Please be aware that my.xfinity.com has recently dropped support for IE10 and below and we recommend your team also works on a timeline to drop support. If you still need to support those browsers, you'll need to use the legacy Polaris. Lastly, legacy Polaris will be ended at the end of 2017.

Accessibility

Polaris has been fully tested by the Accessibility team at Comcast and has 0 open issues. :-)

Installation

Adding the new Polaris to your site is simply including a script tag. Our server is setup to return an optimized version of polaris depending on the users browser and if it has customElements + JS Class support. If you find any browser not working correctly please let us know in slack #polaris.

<script src="https://polaris.xfinity.com/polaris.js" async></script>
<style>
    xc-header { display: block; min-height: 44px; background: #000; }
</style>
          

After adding the above code, you simply add the new tags to your site. If you don't have a clientId, create one that represents your site!

<xc-header
  tab="myxfinity"
  client-id="YOUR-CLIENT-ID"
></xc-header>

Your site code goes here..

<xc-footer
  client-id="YOUR-CLIENT-ID"
></xc-footer>
          

How Polaris Authenticates

Polaris is a web component and can be completely controlled by the client. Authentication can be accomplished with one of two attributes being added to <xc-header> tag outlined below. By default polaris will do nothing and show the signed out state. You must add one of the two attributes below with is-authed being strongly preferred.

is-authed

You have full control over the auth state of polaris by adding the is-auth attribute. When present, Polaris will try to log the user in with CIMA via an iframe and then make additional calls to get user display name, notifications and email count.

auto-auth

With the auto-auth attribute set, Polaris will check for an isAuth=1 cookie on xfinity.com to determine if the user is logged in with CIMA. If both are true, Polaris will log the user in with CIMA and perform the same actions outlined above.

enable-in-home-auth

With the enable-in-home-auth attribute set, Polaris will check to see if the user is in-home and authenticate.

IE11 Corp Laptops and Auth Gotcha

IE11 with certain privacy settings will not transfer the cookies needed to authenticate with CIMA in an iframe (happens on corporate laptops). For this reason, auto-auth may not work. Hopefully you are using the is-authed...

How Polaris Shares Data to the Client

When Polaris gets data inside the orchestration iframe, it makes it available to the parent application through a few basic methods.

We will fire a custom event on window, called polaris-data-changed. This event will contain the data received by the api. event.detail.type contains the type of data, where event.detail.response is the response from the api)

We will also add an attribute to <xc-header> (currently polaris-data-user and polaris-data-notifications) to signal that the data is now contained in <xc-header>. Once this attribute is available, you can access this data as shown in the following code example (example would be when polaris-data-user attribute is available):

var header = document.querySelector('xc-header');
var userdata = header.data.polaris.user;
var notificationsdata = header.data.polaris.notifications;
          

Creating Notifications and Toasts

Custom notifications and toasts can be added by using the addNotification and addToast methods available on the <xc-header> element.

var header = document.querySelector('xc-header');

header.addNotification({
    dismissable: true,
    id: 'UNIQUE_ID',
    main: 'Notification Title Goes Here',
    maxViews: 10,
    url: 'http://my.xfinity.com'
});

header.addToast({
    dismissable: true,
    id: 'ANOTHER_UNIQUE_ID',
    links: [{
        text: '',
        url: '',
        id: '',
        message: '',
        data: {},
        target: '_blank'
    }],
    main: 'Toast Title Goes Here',
    sub: 'Subtitle Goes Here',
    maxViews: 5
};
          

Additional Usage

The header has additional attributes that you can use to customize it. Each of the attributes can be set in markup or via javascript using setAttribute or setting the value directly. Additionally you can get information from Polaris such as isAuthed or firstName.

var header = document.querySelector('xc-header');
header.setAttribute('width', 1240);
header.width = 1240;

header.setAttribute('email-count', 150);
header.emailCount = 150;

var firstName = header.firstName;
var isAuthed = header.isAuthed;
//sign user out
header.isAuthed = false;
          

The following attributes are available on xc-header. xc-footer only has clientId, simplefooter, and width.

auth-hide
boolean
Hides signin/signout section. Can still show notifications if auto-auth or is-authed is still enabled.
auto-auth
boolean
Makes polaris try to determine users authenticated state and perform auth as outlined in authentication section.
client-id
string
A required unique identifier for your site. This is primarily used for tracking. (This is NOT the cima client id.) Please add to both header and footer!
cima-client-id
string
This optional attribute allows you to use your own CIMA client id. Please note that this is NOT the same as the above client-id attribute, whis is strictly for polaris tracking.
disable-controller
boolean
Prevents polaris from loading its controller iframe which gets user information, notifications, email count, etc.
disable-email-count
boolean
Prevents polaris from calling YHM for email count.
disable-skip
boolean
Polaris includes a skip-navigation link for accessibility. If you include your own skip link for accessibility, feel free to disable the one in Polaris.
email-count
number
Set the number of unread emails.
enable-in-home-auth
boolean
With the enable-in-home-auth attribute set, Polaris will check to see if the user is in-home and authenticate. If successfully in-home authed, the accessToken will be stored at header.data.polaris.token
enable-notifications
boolean
Allows Polaris to call notifications API.
first-name
string
Users first name
is-authed
boolean
Users current authed status
notifications
object
This must be set via javascript. See the `Show Notifications` demo and source code if you want to add your own notifications. This will eventually become more of an api like header.notifications.add({MY NOTIFICATION});
orc-enabled
boolean
Set by orchestration layer, indicates two-way communication is ready.
sign-in-delay
number
Delay sign in by milliseconds.
sign-in-url
string
Sets the url when a user clicks signin
sign-out-url
string
Sets the url when a user clicks signout
sign-out-override
boolean
override to sign out only from sign-out link
simplefooter
boolean
Shows "simple footer". (<xc-footer> only)
simpleheader
boolean
Shows "simple header".
slimnav
boolean
Shows "slim nav" with Xfinity and Comcast Business links.
state
string: ['authenticated', 'recognized', 'unrecognized']
Users not signed in are considered recognized if they are on the Comcast network, otherwise they are unrecognized.
tab
['myxfinity', 'shop', 'support', 'myaccount', 'tv', 'email', 'home', 'internet', 'voice']
Sets the selected tab on polaris
width
number
Sets the max-width of Polaris.