Kentico 8 Technology - Social Marketing API
Kentico 8 comes with a new module called Social Marketing, which enables you to post to Facebook and Twitter easily, using credentials stored in Kentico that collect statistics about your posts and tweets. This article shows how to use these features in your own modules and customisations.
In our documentation we describe features that allow you to post a tweet to Facebook directly from Kentico in several ways: from the Facebook app, attaching it with a document using its editing form, or by using a workflow step, which automatically creates a Facebook posts or tweets. Let’s take a tour of this particular API that allows you to do so much with your custom code.
Simple posting
Using Kentico to post to social media pages requires having it configured. This specifically means having at least one set of application information, whether it is a Twitter app or Facebook app and a Facebook page or Twitter channel credentials on behalf of which Kentico will create the posts or tweets. How do you do it?
The functionality is located in the SocialMarketing.dll in the namespace CMS.SocialMarketing. For the purpose of this article as well as with Kentico code, Facebook posts and tweets are referred to as posts, whereas Facebook pages and Twitter channels are referred to as accounts. The following piece of code creates a Facebook post and stores it to the database. The post is only provided with the information about the account it is supposed to be posted to, the site it is associated with, the text of the post and whether the text should be processed by a URL shortener or not. Please note, that macro-expressions in such posts will not be resolved since only document macros are fully supported for posts associated with documents.
FacebookAccountInfo accountInfo = FacebookAccountInfoProvider.GetDefaultFacebookAccount(SiteContext.CurrentSiteID);
FacebookPostInfo postInfo = new FacebookPostInfo
{
FacebookPostFacebookAccountID = accountInfo.FacebookAccountID,
FacebookPostSiteID = SiteContext.CurrentSiteID,
FacebookPostText = Text,
FacebookPostURLShortenerType = URLShortenerTypeEnum.Bitly,
};
FacebookPostInfoProvider.SetFacebookPostInfo(postInfo);
We have a Facebook post in the database. Now we need to send it to Facebook. It is as simple as the following line of code. The whole procedure is very similar to Twitter, you only have to work with TwitterPostInfoProvider and TwitterPostInfo.
FacebookPostInfoProvider.PublishFacebookPost(postInfo.FacebookPostID);
Deleting a post
When you need to delete a post you can do so as you would with any other object info that has a provider in Kentico. Just bear in mind that deleting a post from Kentico will delete it from your Facebook wall or Twitter channel as well. The following line will delete the post from your database and will be unpublished from Facebook. It’s exactly the same for Twitter, except that you need to replace Facebook with Twitter.
FacebookPostInfoProvider.DeleteFacebookPostInfo(post);
A workaround is in place to avoid having the post taken down from your Facebook wall or twitter channel. It’s enough to remove the information that identifies the post for Facebook or Twitter just before calling the delete as is shown in the following example. The same can be done for Twitter.
post.FacebookPostExternalID = null;
FacebookPostInfoProvider.DeleteFacebookPostInfo(post);
Scheduling a post
The auto post control offers you the option to schedule a post either to a determined date and time, or to the same time that the document shall be published. To achieve this, simply provide the date and time you wish the post to be published to your social network of choice. We’ll now demonstrate on Twitter for a change. The following piece of code creates a tweet, initializes it with necessary information, stores it into database, and tells the system to publish when it’s scheduled to.
TwitterPostInfo twitterPost = new TwitterPostInfo
{
TwitterPostTwitterAccountID = accountInfo.TwitterAccountID,
TwitterPostSiteID = SiteContext.CurrentSiteID,
TwitterPostText = Text,
TwitterPostURLShortenerType = URLShortenerTypeEnum.Bitly,
// Tweet will be published two hours from now
TwitterPostScheduledPublishDateTime = DateTime.Now + TimeSpan.FromHours(2),
};
TwitterPostInfoProvider.SetTwitterPostInfo(twitterPost);
TwitterPostInfoProvider.PublishTwitterPost(twitterPost.TwitterPostID);
You are now able to schedule a post. There’s a catch, however. When you need to change the time, a post is scheduled to be published to the social network. There is a scheduled task in the system that is ready to send your post and you need to cancel it. Once more it’s as easy as one line of code. The following example shows how to properly update a post or tweet in case the scheduling might have changed.
TwitterPostInfo twitterPost = TwitterPostInfoProvider.GetTwitterPostInfo(postInfoId);
if (TwitterPostInfoProvider.TryCancelScheduledPublishTwitterPost(twitterPost))
{
UpdateTweet(TwitterPost); // Updates tweet with new data
TwitterPostInfoProvider.SetTwitterPostInfo(twitterPost);
TwitterPostInfoProvider.PublishTwitterPost(twitterPost.TwitterPostID);
}
else
{
// post has already been published an its scheduling could not be canceled. Don't update post in such case.
}
Macros and Documents
It has been mentioned above that posts associated with documents can contain macros in their text. This means that a post not connected to any document will not have any macros resolved and will be published as is. Posts tied to a document will, on the other hand, have all macros in their text resolved, but beware of contextual macros. Macros are resolved out of context. Avoid using contextual macros in posts.
How do you couple a post with a document? The following example demonstrates a Facebook post tied to a document. The key is to provide the post with the GUID of the document you want the post to be associated with.
FacebookPostInfo facebookPost = new FacebookPostInfo
{
FacebookPostFacebookAccountID = accountInfo.FacebookAccountID,
FacebookPostSiteID = SiteContext.CurrentSiteID,
FacebookPostText = Text,
FacebookPostURLShortenerType = URLShortenerTypeEnum.None,
FacebookPostDocumentGUID = treeNode.DocumentGUID // Document GUID
};
FacebookPostInfoProvider.SetFacebookPostInfo(facebookPost);
The post’s macros will now be resolved when publishing and the post can be published either right now or in the future using scheduling as we’ve demonstrated above, but can also be planned to be published along with the document even when it’s under workflow. The following example illustrates a tweet being rescheduled to be sent to Twitter along with a document being published. Note that there’s a different approach required when the document is under workflow and when it’s not.
// Get the document associated with the post
var treeNode = DocumentHelper.GetDocuments().Published(false).AllCultures().WhereEquals("DocumentGUID", new Guid("8318ffc7-2fb4-4082-bb28-603e150136d9"));
// Indicate that post shall be published along with document.
facebookPost.FacebookPostPostAfterDocumentPublish = true;
bool documentHasWorkflow = treeNode.GetWorkflow() != null;
if (!documentHasWorkflow)
{
// If not under workflow, schedule the post to be published at the same time the document is scheduled to
facebookPost.FacebookPostScheduledPublishDateTime = treeNode.DocumentPublishFrom;
}
// Save the newly updated post
FacebookPostInfoProvider.SetFacebookPostInfo(facebookPost);
if (!documentHasWorkflow)
{
// If not under workflow, schedule the post
FacebookPostInfoProvider.PublishFacebookPost(facebookPost.FacebookPostID);
}
// If document is under workflow, the act of publishing the document via workflow will publish the post as well
URL shorteners
Every post has a property (FacebookPostURLShortenerType or TwitterPostURLShortenerType) that dictates whether or not to shorten links in the post’s text and which shortener to use if any. To use URL shorteners other than TinyURL you need to set them up. If a post or tweet is set to be processed via a URL shortener, all absolute URLs in the text will be shortened using the URL shortener the post has been assigned. Macros are resolved before the text is processed through a URL shortener. We currently support TinyURL, Bit.ly and goo.gl. The shorteners API is available to you as well. You can use it in your customizations to shorten links in any text. The following two lines of code demonstrate how to determine whether a shortener is configured or not, and also processes a text with it.
if (URLShortenerHelper.IsURLShortenerAvailable(URLShortenerTypeEnum.Bitly, SiteContext.CurrentSiteID))
{
String withShortURLs = URLShortenerHelper.ShortenURLsInText(textWithLongURLs, URLShortenerTypeEnum.Bitly, SiteContext.CurrentSiteID);
}
If you need a list of all available shorteners to populate a multi-choice control you can easily get it by using the code snippet below:
List<URLShortenerTypeEnum> shortenerList = URLShortenerHelper.GetAvailableURLShorteners(SiteContext.CurrentSiteID);
If you prefer using a control that is already available and ready to use, you can use the URL shortener selector control.
Future plans
That’s it! This is the overview of how to use Kentico API to post to social media. I hope you enjoy working with Kentico. Please feel free to give us any feedback. Support for other social networks is coming in future versions. Would you like to know how to add support for a social network right now? Let us know! You can always leave us a comment below or make a suggestion on ideas.kentico.com.