This documentation is for Flattr Partners.
You can apply for partnership over at our partnership site.
To take part in revenue sharing with Flattr you need to generate a Revenue Sharing Key on our partner site. This key is unique and used to identify all the flattrs you make as a partner on Flattr.
If you use javascript buttons in your Flattr integration you need to add your revshare key ( available on the partner site to either the Flattr javascript or to a attribute on the Flattr button.
Example: Add revenue sharing key to the Flattr Javascript
<script type="text/javascript">
/* <![CDATA[ */
(function() {
var s = document.createElement('script');
var t = document.getElementsByTagName('script')[0];
s.type = 'text/javascript';
s.async = true;
s.src = '//api.flattr.com/js/0.6/load.js'+
'?mode=auto&revsharekey=YOUR_REVENUE_SHARING_KEY';
t.parentNode.insertBefore(s, t);
})();
/* ]]> */
</script>
Example: Add the revenue sharing key as a data-flattr attribute on the link HTML tag
<a class="FlattrButton" style="display:none;"
title="This is my title"
data-flattr-uid="flattr"
data-flattr-tags="text, opensource"
data-flattr-category="text"
data-flattr-revsharekey="YOUR_REVENUE_SHARING_KEY"
href="http://wp.local/?p=444">
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Lorem ipsum dolor sit amet, consectetur adipiscing
Maecenas aliquet aliquam leo quis fringilla.
</a>
If you are flattering through our REST API you need to make certain that your Revenue Sharing Key is connected to your Application on the partner site. If it is, you won't need to do anything futher.
Partner namespaces is a way for partners to create Things for their users' content without the user having to preregister at Flattr. When the user later on signs up for Flattr they will receive all the pending flattrs and gain ownership of all of their Things.
The mechanism uses non-flattr user identifiers to identify ownership of the things and lets the user claim it's things and flattrs by later confirming that its the rightful owner of that identifier.
Namespaces are created in dialog with Flattr, so contact us and we can discuss futher.
Web Hook Callbacks are supported for notifying partners when something happens to one of their users unclaimed things - such as them receiving flattrs. That way partners can easily communicate what is happening on Flattr to their users and make them aware that they have flattrs to claim..
The first step is to add a way for users to be able to flattr the content on your site.
The best user experience is achieved by using our javascript based embedded buttons which embeds buttons as iframes through which logged in users can flattr right away.
If for any reason embedded buttons won't work one can instead use our static auto-submit to open a page on Flattr.com with the thing on which it can be flattred.
Through the auto-submit process (auto-submitting means that a Flattr thing is created automatically when the first flattr is made - they don't have to be presubmitted) the description of the thing is currently also added - the name, category, language etc.
However - we're looking at moving away from auto-submit provided description data in the future and fetch the description of the thing from its URL instead - using Open Graph data or similar. Partners need to keep this in mind when choosing URL:s for their things. Feedback is also welcome.
Embedded buttons for partners work the same way as a normal Flattr button.
The difference between normal buttons and the ones used by partners is that a partner may assign an owner parameter instead of the uid parameter used by ordinary buttons. The owner parameter contains an identifier for a non-flattr user. See a list of supported identifiers in the section Supported user identifiers at the end of this document.
The static auto-submit is a link that redirects to either an existing thing or to a temporary page where the thing can be flattred and thus also created through the auto-submit.
The basic URL for the static auto-submit is https://flattr.com/submit/auto and to that a couple of query parameters are added see embedded button documentation.
As with the Embedded buttons, a partner may assign an owner instead of the uid parameter.
Example Auto-submit URL
https://flattr.com/submit/auto?url=http://example.com/&owner=twitter:user:id:123&title=Example
For partners to get notified when something happens to their site's unclaimed things we have added support for web hooks - this means that partners can pass the notification on to the owner of thing so that partners can be sure that the user knows about it.
A single web hook URL is registered with us and which events that should be sent to it. Whenever an event occurs we do a POST-request to that URL with a form encoded body containing event specific parameters as well as a _event parameter indicating the type of event. Partner sites should always check the _event parameter prior to processing an event to be sure that they are processing the right event.
Event name: pendingclickcreate
Parameters:
email:05f8b3480b04f6a516bb1a46e556323ctwitter:user:id:123partner:customnamespace:123If you think a identifier is missing don't hesitate contacting us about it.
If we have arranged it so that you can verify that a given Flattr account is owned by a user on your system, you can use a API call to associate the two accounts. This will make all pending things associated with the user on your system to automatically be claimed by the Flattr account.
partner:customnamespace:123 where 123 is e.g. the ID number of a user on your system. Contact us if you do not know what your partner namespace is.POST https://api.flattr.com/rest/v2/users/:username/verify
POST https://api.flattr.com/rest/v2/user/verify
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Current: 1
X-RateLimit-Reset: 1342521939unauthorized (401 Unauthorized) - You are either not logged in, are providing an invalid identifier, or are not allowed to verify the provided identifier.