Upsight logo Back to top

Marketing

Marketing Integration


Marketing

The Upsight SDK uses a concept of 'Billboards' and 'Milestones' for delivering content to mobile and web devices.

Note For web devices, the marketing campaign type you must choose is "Native Messaging". These campaigns allow you to add values for several different data types, including text, images, and colors. Once the campaign values have been sent down to your app, you can use them to assemble your final creative.

Native Messaging

Milestones are Upsight's way of triggering requests to retrieve content from our API. When a Milestone is triggered, the API will determine whether content is available for a particular Milestone. If content is available, the API will deliver the specified content to the end user's device where it will be stored by the SDK. Billboards, on the other hand, are Upsight's mechanism for displaying content delivered to the SDK. Milestones and Billboards are decoupled and can each be created without any dependency on the existence of the other object. However, in order for content to be successfully delivered, instances of Milestone(s) and Billboard(s) with matching scopes must be present. For example, if an event in your application triggers a Milestone with scope: "foo", the SDK will check to see if a Billboard instance with the identical scope: "foo" exists. If a match is found, the SDK will attach the content from the Milestone to the matched Billboard. If a match is not found, the content from the Milestone will be stored and placed in a queue until a Billboard with an identical scope is intialized.

To provide more context as to how content is delivered using Upsight, let's go ahead and create a billboard:

var handlers = {
  onData: function(content) {},
  onDetach: function() {}
};
upsight.createBillboard('foo', handlers, function(billboard) {
  console.log(billboard); // Logs the create billboard instance
});

The code snippet above creates and returns a new Billboard instance with the scope "foo" to the provided callback method. The 'handlers' object passed as the second argument manages any actions to be taken once content is available, which is explained below. Additionally, the 'handlers' object is responsible for doing anything when the Billboard instance is destroyed.

Now that we have created a Billboard instance with scope: "foo", we are ready to attach content to our initialized Billboard by recording a milestone with a matching scope value.

upsight.recordMilestone('foo');

Since there is a matching Billboard instance with the scope: "foo", the received content for the Milestone automatically attaches to the Billboard instance and the onData method will be executed. A 'content' object is passed as an argument to the 'onData' method which the developer can interact with readily. See Content for more information about its various methods.

var handlers = {
  onData: function(content) {
    var data = content.getJSON();
  },
  onDetach: function() {
    // do something
  }
}
upsight.createBillboard('foo', handlers);
upsight.recordMilestone('foo');

When the 'onData' method finishes execution, the Billboard instance's default action will be to destroy itself. However, if the developer saved a reference to the 'content' object before the billboard is destroyed, the developer would still have access to the 'getJSON' method of the 'content' object, but will be unable to execute any of the event recording methods.

var myContent;
var handlers = {
  onData: function(content) {
    myContent = content;
  }
};
upsight.createBillboard('foo', handlers, function(billboard) {
  upsight.recordMilestone('foo', undefined, function() {
    // The billboard will have been destroyed by this point because the
    // content was successfully attached to the Billboard.

    var data = myContent.getJSON(); // Still returns data properly
    myContent.recordDismissEvent(); // Does nothing
  });
});

In order to override the default behavior and prevent a billboard from automatically destroying itself, the developer must return the 'KEEP_ALIVE' flag provided by the 'content' in the 'onData' method.

var myContent;
var handlers = {
  onData: function(content) {
    var data = content.getJSON();
    return content.KEEP_ALIVE;
  },
  onDetach: function() {
    // do something
  }
};
upsight.createBillboard('foo', handlers, function(billboard) {
  upsight.recordMilestone('foo', undefined, function() {
    // Since the `KEEP_ALIVE` flag was returned in the `onData` method of the
    // handler, the event recording method will work properly.

    var data = myContent.getJSON(); // Still returns data properly
    myContent.recordDismissEvent(); // records a 'content_dismissed' event
    myContent.destroy(); // dismisses the content
  });
});

Note A new Billboard cannot be created using an existing Billboard scope. The developer must destroy the existing Billboard for a specific scope before trying to create a new Billboard with that same scope. When a billboard is destroyed, the 'onDetach' method will be invoked. Within the 'onDetach' method, a developer can perform any clean up after displaying the delivered content. To destroy the Billboard instance manually, simply invoke the 'destroy' method from the instance.

var handlers = {
  onData: function(content) {
    var data = content.getJSON();
    return content.KEEP_ALIVE;
  },
  onDetach: function() {
    // do something
  }
};

upsight.createBillboard('foo', handlers, function(billboard) {
  billboard.destroy();
});

It is also important to note that Milestones can be triggered prior to initializing a Billlboard in order to preemptively deliver content to the SDK, so that the desired content is fully downloaded and available before a corresponding Billboard is created. Using this methodology, developers can better optimize their content delivery performance

upsight.recordMilestone('foo', undefined, function() {
  // check to see if there is already a billboard for the scope before trying
  // to create a new one
  upsight.getBillboard('foo', function(billboard) {
    if (!billboard) {
      var handlers = {
        onData: function(content) {
          // do something with the content data
          var data = content.getJSON();

          return upsight.KEEP_ALIVE
        }
      };
      upsight.createBillboard('foo', handlers);
    }
  });
});