Note: This article should not be used for HTML/Javascript based widgets. Those widgets should use the functions provided by the widget framework.

You can log attention events to NewsGator by sending an HTTP request with certain parameters on it. This can be done in a variety of way, for instance by using the URLLoader class.

The endpoint URL is http://nmp.newsgator.com/ngbuzz/attn.ashx

The endpoint accepts the following arguments:

1.       buzzId (required) - The numeric ID of the widget to log against, or the name of the widget (if name is sent, orgCode is required)

2.       orgCode - The orgCode the widget is from. Only required if buzzId is a name rather than a numeric ID.

3.       eventName (required) - the name of the event to log. See paragraph on Event Types.

4.       trkP - The parent widget's tracking GUID, if any. If the parent widget had a tracking GUID this must be sent to correctly identify the instance. Otherwise it may be omitted. Properly creating and handling trkM and trkP is the topic of another article.

5.       trkM - This widget's tracking GUID, if any. For descendant widgets this must be sent to identify the widget instance, for the root/non-descendant instance it may be omitted. Properly creating and handling trkM and trkP is the topic of another article.

6.       mid - The buzzId of this widget's master widget, if any. Required if this widget is a subordinate widget, otherwise must be omitted.

7.       pid – (optional) The Newsgator PostID that the event is related to. This is never required, and should only be sent for events that are related to a specific post such as emailing, rating, or clicking a post link. This should never be sent for non-post specific events such as sharing the widget, or clicking on header/footer images.

Event Types

The following events are supported. These should be used in the eventName parameter.

1.       view - This indicates that a widget was rendered. For simple widgets this is straightforward. For complex widgets such as Checkbox or Tabs, the behavior and meaning of this depends on how the widget is written. This event is automatically logged by the widget framework. You will only need to log this event in cases where your Flash/Flex widget is included directly on the page, without being wrapped in an HTML widget such as on MySpace.

2.       click - Indicates that the user has clicked through to the source content. This is a very important metric as it indicates revenue opportunities for widget clients.

3.       rate - Indicates that a user clicked the ratings stars in the toolbar.

4.       clip - Indicates that a user clipped/saved a post.

5.       im - Indicates that a user sent the post via IM.

6.       email - Indicates that the user sent the post using email.

7.       comment - Indicates that the user commented on the post.

8.       custom1 through custom9 - These events are not defined. Any widget may use them in any way it sees fit. Custom1 is used by the default Accordion template to indicate clicks on an accordion header, and by the default Paging template to indicate paging forward/back. Currently all custom events roll up under “other interactions” in our reporting interface. Also, NewsGator has developed internal conventions for these events. You are not required to follow them, but you may wish to. They are described in the KB article “Keeping Track of User Interaction In Your Widgets”, http://newsgator.mykbpro.com/Article_AC95F.aspx

Example requests:               

Log a click event for buzzId 5694 on post 123465
http://nmp.newsgator.com/ngbuzz/attn.ashx?buzzId=5694&eventName=click&pid=123465

Log a click event for widget “Demo” in orgcode “test” for post 123465

http://nmp.newsgator.com/ngbuzz/attn.ashx?buzzId=Demo&orgCode=test&eventName=click&pid=123465

Log a custom1 event for a descendant of widget 5694
http://nmp.newsgator.com/ngbuzz/attn.ashx?buzzId=5694&eventName=custom1&trkM=ABD13BB2-54DE-48D5-B729-3B6BDA7ADDAC

Log a custom1 event for a different descendant of widget 5694
http://nmp.newsgator.com/ngbuzz/attn.ashx?buzzId=5694&eventName=custom1&trkP=ABD13BB2-54DE-48D5-B729-3B6BDA7ADDAC&trkM=493F7453-A1AB-43E4-BD6A-C38609A66C6B

ActionScript:
The following is some basic ActionScript code that should get you through most scenarios:

public function logEvent(attentionDataType:String, buzzId:String, postId:String="", orgCode:String="", trkM:String="", trkP:String="", referrerUrl:String=""):void
 {
                var cacheBreaker:String = new String(Math.random()); //used to ensure response isn't cached
                var additionalParams:String = "";

                if (orgCode != "")
                {
                                additionalParams += "org=" + encodeURIComponent(orgCode);
                }

                //add param if not empty
                if (trkM != "")
                {
                                additionalParams += "&trkM=" + encodeURIComponent(trkM);
                }

                //add param if not empty
                if (trkP != "")
                {
                                additionalParams += "&trkP=" + encodeURIComponent(trkP);
                }

                // add param if not empty
                if (postId !="")
                {
                                additionalParams += "&pId=" + encodeURIComponent(postId);
                }

                if (referrerUrl != "")
                {
                                additionalParams += "&u=" + encodeURIComponent(referrerUrl);
                }

                //compose url
                var req:URLRequest = new URLRequest("http://nmp.newsgator.com/NGBuzz/attn.ashx?"
                                + "eventName=" + encodeURIComponent(attentionDataType)
                                + "&t=" + encodeURIComponent(cacheBreaker)
                                + "&buzzId=" + encodeURIComponent(buzzId)
                                + additionalParams);

                //kick off request to the url
                var loader:URLLoader = new URLLoader();
                loader.load(req);
 }