Today I Learned: How to Enable Flash Developers

Not having Flash development experience in-house, we were puzzled recently when we received a support request from a Flash guy wondering why a file we’d never heard of (crossdomain.xml) was giving a 404 file not found error when he requested it. Because it wasn’t there, obviously.

Thankfully, the developer in question was kind enough to throw us a link about why that file was needed for Flash, and a few minutes later we had everything we needed to know. Thanks, Chad!

So if you’re a Flash developer, crossdomain.xml is now available on our servers to permit you to use FeedBlitz-powered RSS feeds in flash apps hosted on your domain. Neat.

New: RSS Image Enclosures Now Visible

A funny (peculiar, not haha) thing about major media site RSS feeds is that not only are the feeds often little more than a plain text (and so kinda boring) sentence, but also that their RSS feeds tend to include thumbnail images as enclosures. Enclosures are the part of a feed typically used for podcast media files, and the problem with stashing an image as an enclosure is that most people won’t see it, since the picture isn’t part of the main content. As a result, the feed and downstream feed usage (e.g. email subscriptions) are much less engaging for us carbon based life forms, and so the feed produces less traffic back to the publisher’s site than it otherwise might.

We like engagement. You like engagement! Everyone likes more of the right kind of traffic.

So we have fixed this for FeedBlitz publishers.

From now on, if FeedBlitz finds an image enclosure in a feed and there are no other images in the main content, it will bring that image up into the main content (just above the social sharing icons) to make it visible to people. This will make the feed much more engaging, and encourage click throughs.  FeedBlitz will leave the enclosure as it found it, however, in case there are downstream apps that expect and need that image file to be in the feed as an enclosure element. Or, in other words, the change is backwards compatible with the way the feed XML was formatted before.

Too many words? Perhaps an example will help. Here’s a feed whose images are now visible to mere mortals because of this new capability: http://feeds.feedblitz.com/fremont/sports

The FeedBlitz API: Workflow for Building a Plugin

The goal of this example is to show you what API calls to make so you can programmatically add a subscriber’s email (and other information) to a list at FeedBlitz. Let’s assume you’re developing a plugin for WordPress; any WP plugin developer should be able to integrate with FeedBlitz! The example below isn’t limited to plugins, of course; it can work with any web site, product or service you can extend programmatically.  You use simple Web requests, so it’s pretty easy for a web developer to do.

Prerequisites

The user of your plugin will need:

Workflow

Once you’ve validated the pre-reqs, you:

  1. Get a list of the publisher’s active lists from the REST API.
  2. Optionally get a list of custom fields and tags the publisher already has in FeedBlitz.
  3. In your configuration UI, the publisher:
    1. Picks a list that your plugin will subscribe visitors to.
    2. Optionally selects the custom fields to use, or specifies new ones using your UI.

When a visitor uses your plugin to join a list, you then:

  1. Present your UI, performing any necessary validation;
  2. Call the FeedBlitz Simple API to create the subscription
  3. Assuming all is well, FeedBlitz starts the dual opt-in process to add the subscriber.

In Detail

All URLs below are simple HTTP GETs (see, I said it was easy!)

Get a List of Active Mailing Lists

Use a quick call to the REST API as follows

https://www.feedblitz.com/f.api/syndications?key=<api_key>&summary=1

The returned XML will contain one or more <syndication> elements, one for each active list. Grab the <id> and <name> elements within each. You will need to persist the <id> that the user selects. Add “text/xml” to your Accept-Type header to make the REST API work.

Get Active Custom Fields

If the publisher has custom fields defined in their account, it would be nice to offer those on your UI, right? Right! Here’s the REST API call:

https://www.feedblitz.com/f.api/fields?key=<api_key>

The returned XML may contain or more <field> elements. Grab the <name> and the <id> and the <uihidden> elements. FeedBlitz allows publishers to create hidden custom fields; publishers can use hidden fields to track campaigns, referring pages, etc.  Hidden fields should not be displayed to end users (i.e. not shown to site visitors or potential subscribers); it’s obviously ok to show them to the publisher during set up. If there are no custom fields defined, you can also offer your own (e.g. “Name”); FeedBlitz will add them when you send the data to FeedBlitz at subscription time. Again, this a REST API call, so be sure to add “text/xml” to your Accept-Type header before accessing the resource.

Save the relevant information and use it to build the user interface you want to present to site visitors.

Subscribe a visitor

Configuration all done, potential subscribers will now be using your user interface on the publisher’s web site. Based on the saved configuration and user-supplied data, and making sure as best you can that the visiting user agent is not a bot (recommended to prevent spambots: use <script> to generate your UI on the fly, and make sure there’s a valid referrer header); call the simple subscription API as mentioned last week with the correct parameters:

https://www.feedblitz.com/f?SimpleApiSubscribe&key=<api_key>&email=<email>&listid=<listid>

 Optionally add tags and name / value pairs, again as mentioned over here.

Done!

It’s that easy. Two calls to assist in configuration, and one per new subscriber. FeedBlitz handles the entire dual opt-in process from there on, as well as all subscriber management such as bounce handling, unsubscribes etc.

The FeedBlitz REST API

The REST API is an XML-based API. It is, like FeedBlitz itself, complex and at times may be challenging to use. For simple use cases, such as integrating a FeedBlitz subscription mechanism into your site or service, we recommend using one of the APIs I’ve already covered this week, or a plugin / widget that has already done the work for you.

If you’re building such a plugin, widget or tool, then depending on your use cases you may need to delve into the REST API in some depth.


Programming Required: Yes
API Key Needed: Yes
Best suited for: Web developer, plugin developer
Skill level: Intermediate to Advanced
Good for: Programmatic control over almost all FeedBlitz capabilities


The REST API has lots of features relating to detailed list settings, subscribers and more, so plugin developers can use it to discover a publisher’s lists and custom fields, for example. Although the REST API is rich and complex, these basic tasks are fairly easy to do, especially if you’re only reading data, since that requires nothing more than the ability to parse basic XML and send a simple HTTP GET request in your code.

The full API is documented in a PDF, available for download from www.feedblitz.com/api

The FeedBlitz Simple API: Adding Subscriptions Programmatically

If you’re a plugin developer, PHP guru, or a web programmer who wants to do more with FeedBlitz but the REST API is daunting, we’re rolling out a new set of features in a “Simple” API that is much easier to use.  This API needs an API key, which you can get here after you log in.


Programming Required: Yes
API Key Needed: Yes
Best suited for: Web developer, plugin developer
Skill level: Intermediate
Good for: Adding a subscriber from a popup, plugin, or web site back end


The function of this “Simple” API is to start the FeedBlitz dual opt-in process for a new subscriber, add custom fields along the way, all in a completely programmatic way. Any initial UI (user interface) presented prior to that is the responsibility of you, the developer, to build. This API is email only; it cannot add any of FeedBlitz’s supported social media subscriptions.

The simple API is just a common or garden web page request (an HTTP GET, for the technically minded), as follows:

https://www.feedblitz.com/f?SimpleApiSubscribe&key=<api_key>&email=<email>&listid=<listid>

The following parameters are required:

<api_key> The publisher’s API key, URL encoded
<email> The email you want to add to your list, URL encoded.
<listid> The ID of the list to add the subscriber to.

The list id is displayed on each list’s dashboard, under the list’s title and description.

Additionally, there are optional parameters you can supply to the API, to tag a subscriber and / or add custom fields to their record.

To tag a subscriber, e.g. to add product purchase information, you supply a tags parameter, of the form tags=<taglist> where <taglist> is a comma separated, URL encoded list of tags to apply to the subscriber (tags are added as custom fields, with the value “1”).

To provide custom field data, e.g. names, zip codes, etc., you may optionally provide other parameters in the URL as name / value pairs. The name will be treated as a custom field name, and the value the value to assign to that field for this subscriber. If the custom field doesn’t exist, it will be created.

Examples

Here are some examples, assuming the API key for the FeedBlitz account owning list 84 is “Abc123”, to help show how to use this API:

  1. https://www.feedblitz.com/f?SimpleApiSubscribe&key=Abc123email=phil%40example.com&listid=84
     
    Starts the dual opt-in for phil@example.com to list 84.
     
  2. https://www.feedblitz.com/f?SimpleApiSubscribe&key=Abc123email=phil%40example.com&listid=84&tags=Widgets
     
    Starts the dual opt-in for phil@example.com to list 84, tagging the user with the “Widgets” tag.
     
  3. https://www.feedblitz.com/f?SimpleApiSubscribe&key=Abc123email=phil%40example.com&listid=84&tags=Widgets,Boxes,Stuff
     
    Starts the dual opt-in for phil@example.com to list 84, tagging the user with three tags: Widgets, Boxes and Stuff.
     
  4. https://www.feedblitz.com/f?SimpleApiSubscribe&key=Abc123email=phil%40example.com&listid=84&Name=Phil%20Hollows
     
    Starts the dual opt-in for phil@example.com to list 84, and assigns the value “Phil Hollows” to the custom field called “Name”
     
  5. https://www.feedblitz.com/f?SimpleApiSubscribe&key=Abc123email=phil%40example.com&listid=84&tags=CampaignX&FirstName=Phil&LastName=Hollows
     
    Starts the dual opt-in for phil@example.com to list 84, and assigns the value “Phil” to the custom field called “FirstName”, “Hollows” to the “LastName” field, and tags the subscriber with the “CampaignX” tag.
     

What Happens

If the API call is successful, the API will return list-specific XML and start the dual opt-in process; it is up to the developer using the API to generate the UI update appropriate to their platform to tell the visitor to check their inbox. If unsuccessful, the reason for the failure will be returned in error XML of the form:

<rsp stat=”fail”>
<err code=”-1″ msg=”Specified list not owned by this client account” />
</rsp>

The reason for the failure will be in the msg attribute of the <err> element.

Next up is a post about the REST API. Next week I’ll provide some sample workflows on how to use these APIs in a more-or-less real world example.

The FeedBlitz API: Email Parsers

Email parsers allow FeedBlitz to add email addresses to a mailing list based on a notification email from any third party solution. FeedBlitz grabs the incoming email notification using a “parser,” splits it up into its component parts, then extracts the data to add the subscriber (and other information about the subscriber) to a list.


Programming Required: None
API Key Needed: No
Best suited for: Site publisher, web admin / designer
Skill level: Intermediate
Good for: Adding a subscriber from a third party product or service


You need to be able to manage notifications from the third party system, or set up email forwarding from your inbox, so that you can get the email notification (e.g. a product purchase) to the relevant email address in FeedBlitz (Careful! Some third party systems will need the FeedBlitz email address to be opted in to their email database; that’s OK, just don’t forget to do it!).

Parser Configuration Process

Here’s how to set it up:

  1. Print out a sample notification email from your third party product or service.
  2. Log into your account at FeedBlitz. Pick the list you want to pick up the new subscriber from the dashboard.
  3. From the “Subscriber Management” tile, select “Parsers” from the options in the footer.
  4. Set up the parser according to the email you printed out. Have the parser configured to always email the account holder’s email address. Use the popup help options by each field on the screen to help guide you. If you need help doing this, contact FeedBlitz tech support.
  5. Manually forward your sample email (the one you printed in (1)) to the parser’s email address. In about a minute it will email you with information about whether it worked or not.
  6. Fix any issues from (5) and repeat.
  7. Enable automatic forwarding of emails from your third party service.
  8. Once you’re Ok that it’s all working correctly, change the parser’s email notifications to you to be on mismatches only.

What Happens

FeedBlitz interprets the email notification according to the rules you define. If a new subscriber’s email is detected, FeedBlitz adds the subscriber to, or removes them from, the specified list, as well as any tags (which are added as custom fields with the value “1”).

If a subscriber is added to a list, FeedBlitz starts the dual opt-in process (which means that parsers are not ideal if the third party service has already performed a dual opt-in cycle).  If the parser is attached to an autoresponder, for example when the notification is from a shopping cart and you want to thank the subscriber for purchasing, the sequence starts immediately.

The FeedBlitz API: Simple Subscription Links

These links (URLs) allow a user to start the dual opt-in process. You can put these URLs in a sidebar, an email signature, or a web site widget. Using these links, you can ask a user to subscribe anywhere a URL can be used.


Programming Required: None
API Key Needed: No
Best suited for: Site publisher
Skill level: Basic
Good for: Adding a subscriber to your list


Getting the subscription form link

To generate the subscription URL you need to use, take the following steps:

  1. Log in to your account at FeedBlitz. Pick the list you want to add the subscriber to from the site dashboard.
  2. Click the “Form Code” button.
  3. Configure the subscription options (use “Email only” to keep things really simple).
  4. Copy the link generated and place wherever you want to use it.

If you have dynamically generated feeds where it’s difficult to generate all the mailing lists you want to use up front, you can instead subscribe the user to a feed or blog URL, and associate it with your publisher account. Learn more at http://support.feedblitz.com/customer/portal/articles/873997-subscribe-to-any-feed-or-blog-url – Developers can create custom forms, plugins and other user interfaces whose function is simply to generate this URL to start the dual opt-in process.

What Happens

FeedBlitz will present the subscription form for the content. When the user completes the form, FeedBlitz will go through the standard dual opt-in process.

Getting to Grips with the FeedBlitz APIs

This week on the blog we’ll be running a series on how, if you want to access FeedBlitz programmatically, to pick and choose the right API (Application Programming Interface) to use. We’ll wrap it up with a couple of quick examples to help folks such as WordPress plugin developers get started quickly.

FeedBlitz has evolved several ways for third parties to interact with the service. These include:

  • URLs to start the subscription process to a site or list for end users;
  • Email parsers to enable subscriptions from third party email notifications;
  • A new, “simple” API, allowing easy programmatic third party form integrations — this API is great for plugin developers;
  • A fully-featured REST API to control many aspects of the service programmatically;
  • An OEM API for select partners to FeedBlitz to be embedded on a white label basis.

Each of these techniques is targeted towards different audiences with different needs; they also demand differing levels of web programming expertise, from none to much, to use.

Which API you need to use depends very much on what you want to do and the tools you’re comfortable using. For the most common application, subscribing a visitor, there are many different ways to achieve this task.

Getting a FeedBlitz API Key

Some (not not al!) of these APIs will need what’s called an “API Key” — if you’re a developer (or a publisher with a more-or-less tame developer close at hand) and want to get ahead of the curve, you can get your API key ahead of time at https://www.feedblitz.com/f?pl_api

API keys are case sensitive; keep your API key confidential. FeedBlitz may revoke a key at any time if we feel that it is being abused.

Third party developers building apps and plugins that interact with FeedBlitz should use their own API key to develop and test with. We expect third party developers to require a FeedBlitz API key for most projects, such as building popups or other subscriber acquisition solutions, and that they will require their users (site owners, publishers, bloggers) to get their own FeedBlitz API key. You can use the API key URL above to direct your users to the correct page at FeedBlitz with a single click.

Easy Does It

We’ll start out quite gently in the next post discussing subscription APIs that don’t require you to be a programmer. Bunny slope stuff. After that, the APIs get to be more powerful! Hang in there; this really could be fun, and I promise to warn you when we’re about to hit a double black diamond trail.

Exit Popups: List Growth, But Too High a Price?

Popups work. A somewhat ugly, but nonetheless true fact. Sadly, I feel they’re often abused by publishers who mistake list volume for list quality, and hurt their reputation in the process. Let’s face it, we’ve all visited those web sites where we’re instantly slammed with a popup demanding our email address, and who here actually enjoys that? Precisely.

So we here at FeedBlitz believe in respectful popups — popups that treat visitors kindly, and that wait for proven engagement before asking for the subscription. Combined with appropriate incentives, a respectful popup can be very successful, accelerating the addition of high quality names to your mailing list.

Given that context, then, we were asked recently what we thought about exit popups — a window that appears as a subscriber navigates away from your web site. While possibly effective in the short term, our gut reaction is ugh. We feel that exit popups are fairly user hostile and not respectful of the visitor’s intent to leave a site. As such, we are not fans. In short, if you haven’t successfully engaged the visitor while they’re on your site, then we feel that stopping them from leaving with a forced interaction is at best rude, and at worst spammy.

Would you want to be stopped from leaving a page when you want to? No? Then don’t do it to your visitors either.

Your mileage may, of course, vary. By all means, test, if you think an exit popup is worth a shot and (in our opinion) worth treating your visitors less than kindly. One final data point, though. When FeedBlitz checks a newsflash email blast before it’s mailed, one of the things FeedBlitz does is check the landing pages that mailing links to for exit popups. If it finds one, it raises the spamminess score we assign for that mailing significantly. Too spammy, and that mailing won’t go out, and the presence of an exit popup greatly increases that risk. In our experience, exit popups are generally indicative of poor quality content, overly aggressive attempts to collect email addresses, and smack somewhat of desperation. Is that the image you want to portray?

It’s better to treat your visitors the way you want to be treated. Your reputation is everything — especially when it comes to marketing.

Need a FeedBlitz API Key? Permission Granted

FeedBlitz API key generation has now been made automatic; the prior manual approval process has been eliminated.

Meaning: You can use our API keys in third party integrations without delay.

Implication: More uses for FeedBlitz’s APIs are coming soon.

Access: Log in to your FeedBlitz account, it’s under My Account | API Keys in the left sidebar.

Restrictions: None beyond the requirement that you must be a premium FeedBlitz publisher.

By the way: If your current API key appplication was still pending under the prior policies, simply cancel it and then generate a new key.