Developer Guide

Grab a coffee and get started ...

Integration Examples

In this section we will give you a detailed, step by step, guide for how to implement ‘Pay with a Tweet’. Each example has a variety of integration methods that depend on how you want to embed the campaign, what kind of membership you have and how complex/secure the integration needs to be. We try to give you as many embed examples as possible but of course there are many more ways of combining features and embed methods. Feel free to contact us for any questions via support@paywithatweet.com.

Instant Discount

This example will show you how to embed a ‘Pay with a Tweet’ campaign within a checkout process. The customers receive their discount instantly after posting about their shopping-experience, without having to enter a voucher code manually.

This integration method can be used by all membership types. Please be aware that cookies do not always work due to 'do not track' settings. In addition, if you are giving away content with a lot of value we recommend upgrading to Business as it allows for maximum security via custom parameters, JS events or API.

Embed Codes

Developer:
If a Pay with a Tweet campaign has not yet been created, please click here and follow the steps for creating a campaign. Once the campaign has been created, you will be directed to the embed page. There, you will have a choice between two embed methods. In this scenario you will be using neither custom parameters nor JS events, therefore you can choose between the direct link and the JS embed codes.

Shopping Cart (no discount applied yet)

User:
A user has filled their shopping basket and now clicks to check out. He enters your check out page, on which you have embedded your Pay with a Tweet campaign. The campaign gives a 10% discount on the shopping basket. The user clicks the Pay with a Tweet button.

Set Cookie

Developer:
Set a cookie to save any information you need to apply the right discount to the right user e.g. user ID, shopping cart ID, game world etc.

Sharing Process

User:
The user enters the three-step sharing process. After a successful share the “Access” button will appear (you can customize the text to something else e.g. “Shop Now” or “Get Discount” as part of our white-label settings).

Request Access

User:
The user clicks on the access button.

Verify Post

Developer:
Once your system receives the request from the URL, which you provided us with in the campaign creation process, complete a referrer check to make sure that the user originates from either www.paywithatweet.com or www.paywithapost.de.

Read Cookie

Developer:
Read out the cookie, which you set in step 3.

Apply Discount

Developer:
Apply the discount directly to the shopping basket (aside from triggering the request to your system, the access link should have directed the user back to the checkout process).

Order complete

User:
The user sees the discount and confirms the order.

This integration method uses custom parameters and therefore can only be used by Business accounts. Some of the steps that we show might be redundant or unnecessary. However, we want to show you a wide variety of ways to integrate campaigns so that you can pick the best method for you.

Embed Codes

Developer:
If a Pay with a Tweet campaign has not yet been created, please click here and follow the steps for creating a campaign. Once the campaign has been created, you will be directed to the embed page. There, you will have a choice between two embed methods. In this scenario you will be using custom parameters and therefore must use the JS embed codes.

Shopping Cart (no discount applied yet)

User:
A user has filled their shopping basket and now clicks to check out. He enters your check out page, on which you have embedded your Pay with a Tweet campaign. The campaign gives a 10% discount on the shopping basket. The user clicks the Pay with a Tweet button.

Set Parameters (requires Embed-Code)

Developer:
Pass custom parameters to the JS embed code with any information you need to apply the right discount to the right user e.g. user ID, shopping cart ID, game world etc.

Note:
For extra security, one of the custom parameters could be a user-specific or unique code that is later used to check whether the user has simply copied the access URL or has actually gone through the whole process. For more information about the JS embed codes, custom parameters and JS events, please click here.

Sharing Process

User:
The user enters the three-step sharing process. After a successful share the “Access” button will appear (you can customize the text to something else e.g. “Shop Now” or “Get Discount” as part of our white-label settings).

Request Access

User:
The user clicks on the access button.

Verify Post

Developer:
Once your system receives the access request, complete a referrer check to make sure that the user originates from either www.paywithatweet.com or www.paywithapost.de.

Receiving Parameters (requires Embed-Code)

Developer:
Read the custom parameter, which you set in Step 3. If you assigned an user-specific parameter or an unique code for extra security, verify the request now.

Apply Discount

Developer:
Apply the discount directly to the shopping basket (aside from triggering the request to your system, the access link should have directed the user back to the checkout process).

Redeem Discount

User:
The user sees the discount and confirms the order.

This integration method uses custom parameters and API. Therefore, only Business accounts will be able to use this embed method. Some of the steps that we show might be redundant or unnecessary. However, we want to show you a wide variety of ways to integrate campaigns so that you can pick the best method for you.

Campaign Status

Developer:
Check if the campaign is still active. If your campaign has time or date limitations (you can set them when you create a campaign), you can use the API to check what status the campaign is in. Based on that, you can decide what to show the user. For more details on the API, please click here.

Embed Codes

Developer:
If a Pay with a Tweet campaign has not yet been created, please click here and follow the steps for creating a campaign. Once the campaign has been created, you will be directed to the embed page. There, you will have a choice between two embed methods. In this scenario you will be using custom parameters and therefore must use the JS embed codes.

Shopping Cart (no discount applied yet)

User:
A user has filled their shopping basket and now clicks to check out. He enters your check out page, on which you have embedded your Pay with a Tweet campaign. The campaign gives a 10% discount on the shopping basket. The user clicks the Pay with a Tweet button.

Set Parameters (requires Embed-Code)

Developer:
Pass custom parameters to the JS embed code with any information you need to apply the right discount to the right user e.g. user ID, shopping cart ID, game world etc.

Note:
For extra security, one of the custom parameters could be a user-specific or unique code that is later used to check whether the user has simply copied the access URL or has actually gone through the whole process. For more information about the JS embed codes, custom parameters and JS events, please click here.

Sharing Process

User:
The user enters the three-step sharing process. After a successful share the “Access” button will appear (you can customize the text to something else e.g. “Shop Now” or “Get Discount” as part of our white-label settings).

Request Access

Developer:
The user clicks on the access button.

Verify Post

Developer:
Use the API to verify that this user has actually shared.

Receiving Parameters (requires Embed-Code)

Developer:
Read the custom parameter, which you set in Step 3. If you assigned an user-specific parameter or an unique code for extra security, verify the request now.

Check Validity

Developer:
Use the API to check whether the user has already redeemed the discount on a previous occasion. If not, apply the discount (aside from triggering the request to your system, the access link should have directed the user back to the checkout process).

Redeem Discount

User:
The user sees the discount and confirms the order.

Mark as Redeemed

Developer:
Once the user confirms the order, mark him as redeemed for this campaign.

Download

This examples will show you a ‘Pay with a Tweet’ campaign that uses a download as a reward.

This integration method can be used by all membership types. Please be aware that cookies do not always work due to 'do not track' settings. In addition, if you are giving away content with a lot of value we recommend upgrading to Business as it allows for maximum security via custom parameters, JS events or API.

Embed Codes

Developer:
If a Pay with a Tweet campaign has not yet been created, please click here and follow the steps for creating a campaign. Once the campaign has been created, you will be directed to the embed page. There, you will have a choice between two embed methods. In this scenario you will be using neither custom parameters nor JS events, therefore you can choose between the direct link and the JS embed codes.

Your Website

User:
A User enters your website and can download a “Do It Yourself” guide on your website via Pay with a Tweet. The user clicks the Pay with a Tweet button.

Set Cookie

Developer:
Set a cookie to save any information you might need to trigger the right download. For example, if a user can choose from multiple guides, tell us which one he decided to download for free as a custom parameter.

Sharing Process

User:
The user enters the three-step sharing process. After a successful share the “Access” button will appear (you can customize the text to something else e.g. “Shop Now” or “Download now” as part of our white-label settings).

Request Access

User:
The user clicks on the access button.

Verify Post

Developer:
Once your system receives the download request, complete a referrer check to make sure that the user originates from either www.paywithatweet.com or www.paywithapost.de.

Read Cookie

Developer:
Read out the cookie, which you set in step 3.

Trigger Download

Developer:
Trigger the download (remember to switch the download if there are multiple download options and you used a cookie).

This integration method uses custom parameters and therefore can only be used by Business accounts. Some of the steps that we show might be redundant or unnecessary. However, we want to show you a wide variety of ways to integrate campaigns so that you can pick the best method for you.

Embed Codes

Developer:
If a Pay with a Tweet campaign has not yet been created, please click here and follow the steps for creating a campaign. Once the campaign has been created, you will be directed to the embed page. There, you will have a choice between two embed methods. In this scenario you will be using custom parameters and therefore must use the JS embed codes.

Your Website

User:
A User enters your website and can download a “Do It Yourself” guide on your website via Pay with a Tweet. The user clicks the Pay with a Tweet button.

Set Parameters (requires Embed-Code)

Developer:
Pass custom parameters to the JS embed code with any information you might need to trigger the right download. For example, if an user can choose from multiple guides, tell us which one he decided to download for free as a custom parameter

Note:
For extra security, one of the custom parameters could be a user-specific or unique code that is later used to check whether the user has simply copied the access URL or has actually gone through the whole process. For more information about the JS embed codes, custom parameters and JS events, please click here.

Sharing Process

User:
The user enters the three-step sharing process. After a successful share the “Access” button will appear (you can customize the text to something else e.g. “Shop Now” or “Download now” as part of our white-label settings).

Request Access

User:
The user clicks on the access button.

Verify Post

Developer:
Once your system receives the download request, complete a referrer check to make sure that the user originates from either www.paywithatweet.com or www.paywithapost.de.

Receiving Parameters (requires Embed-Code)

User:
Read the custom parameter, which you set in Step 3. If you assigned an user-specific parameter or an unique code for extra security, verify the request now.

Trigger Download

Developer:
Trigger the download (remember to switch the download if there are multiple download options and you used the custom parameters).

This integration method uses custom parameters and API. Therefore, only Business accounts will be able to use this embed method. Some of the steps that we show might be redundant or unnecessary. However, we want to show you a wide variety of ways to integrate campaigns so that you can pick the best method for you.

Campaign Status

Developer:
Check if the campaign is still active. If your campaign has time or date limitations (you can set them when you create a campaign), you can use the API to check what status the campaign is in. Based on that, you can decide what to show the user. For more details on the API, please click here.

Embed Codes

Developer:
If a Pay with a Tweet campaign has not yet been created, please click here and follow the steps for creating a campaign. Once the campaign has been created, you will be directed to the embed page. There, you will have a choice between two embed methods. In this scenario you will be using custom parameters and therefore must use the JS embed codes.

Your Website

User:
A User enters your website and can download a “Do It Yourself” guide on your website via Pay with a Tweet. The user clicks the Pay with a Tweet button.

Set Parameters (requires Embed-Code)

Developer:
Pass custom parameters to the JS embed code with any information you might need to trigger the right download. For example, if an user can choose from multiple guides, tell us which one he decided to download for free as a custom parameter

Note:
For extra security, one of the custom parameters could be a user-specific or unique code that is later used to check whether the user has simply copied the access URL or has actually gone through the whole process. For more information about the JS embed codes, custom parameters and JS events, please click here.

Sharing Process

User:
The user enters the three-step sharing process. After a successful share the “Access” button will appear (you can customize the text to something else e.g. “Shop Now” or “Download now” as part of our white-label settings).

Request Access

User:
The user clicks on the access button.

Verify Post

Developer:
Use the API to verify that this user has actually shared.

Receiving Parameters (requires Embed-Code)

User:
Read the custom parameter, which you set in Step 3. If you assigned an user-specific parameter or an unique code for extra security, verify the request now.

Check Validity

Developer:
Use the API to check whether the user has already used this campaign to download content on a previous occasion. If not, trigger the download (aside from triggering the download, the access link could have directed the user to a landing page).

Trigger Download

Developer:
Trigger the download, and remember to switch the download if there are multiple download options and you used the custom parameters. Aside from triggering the download, the access link could have directed the user to a landing page for more downloads than just your homepage.

Mark as Redeemed

Developer:
Once the user as completed the download, mark him as redeemed for this campaign

Voucher Discount

This example will show you how to use a ‘Pay with a Tweet’ campaign in combination with voucher codes.

This integration method can be used by all membership types. Please be aware that cookies do not always work due to 'do not track' settings. In addition, if you are giving away content with a lot of value we recommend upgrading to Business as it allows for maximum security via custom parameters, JS events or API.

Embed Codes

Developer:
If a Pay with a Tweet campaign has not yet been created, please click here and follow the steps for creating a campaign. Once the campaign has been created, you will be directed to the embed page. There, you will have a choice between two embed methods. In this scenario you will be using neither custom parameters nor JS events, therefore you can choose between the direct link and the JS embed codes.

Your Website

User:
A User enters your website and is offered a voucher for a 30% discount via Pay with a Tweet. The user clicks the Pay with a Tweet button.

Set Cookie

Developer:
Set a cookie to save any information you might need to give out the right voucher. For example, if you want to differentiate between different discounts based on user segments or shopping basket size, you could pass that information to us via custom parameters.

Sharing Process

User:
The user enters the three-step sharing process. After a successful share the “Access” button will appear (you can customize the text to something else e.g. “Shop Now” or “Get Voucher” as part of our white-label settings).

Request Access

User:
The user clicks on the access button.

Verify Post

Developer:
Once your system receives the access request, complete a referrer check to make sure that the user originates from either www.paywithatweet.com or www.paywithapost.de.

Read Cookie

Developer:
Read out the cookie, which you set in step 3.

Unveil Code

Developer:
Redirect the user to a landing page where you display the voucher code.

Note:
For a better UX, you could include an e-mail form on the landing page so that the user can e-mail the voucher to him-/herself. In addition, you could redirect the user to the checkout page and auto-fill the voucher code into the voucher field using JS.

This integration method uses custom parameters and therefore can only be used by Business accounts. Some of the steps that we show might be redundant or unnecessary. However, we want to show you a wide variety of ways to integrate campaigns so that you can pick the best method for you.

Embed Codes

Developer:
If a Pay with a Tweet campaign has not yet been created, please click here and follow the steps for creating a campaign. Once the campaign has been created, you will be directed to the embed page. There, you will have a choice between two embed methods. In this scenario you will be using custom parameters and therefore must use the JS embed codes.

Your Website

User:
A User enters your website and is offered a voucher for a 30% discount via Pay with a Tweet. The user clicks the Pay with a Tweet button.

Set Parameters (requires Embed-Code)

Developer:
Pass custom parameters to the JS embed code with any information you might need to trigger the right voucher. For example, if you want to differentiate between different discounts based on user segments or shopping basket size, you could pass that information to us via custom parameters.

Note:
For extra security, one of the custom parameters could be a user-specific or unique code that is later used to check whether the user has simply copied the access URL or has actually gone through the whole process. For more information about the JS embed codes, custom parameters and JS events, please click here.

Sharing Process

User:
The user enters the three-step sharing process. After a successful share the “Access” button will appear (you can customize the text to something else e.g. “Shop Now” or “Get Voucher” as part of our white-label settings).

Request Access

User:
The user clicks on the access button.

Verify Post

Developer:
Once your system receives the access request, complete a referrer check to make sure that the user originates from either www.paywithatweet.com or www.paywithapost.de.

Receiving Parameters (requires Embed-Code)

User:
Read the custom parameter, which you set in Step 3. If you assigned an user-specific parameter or an unique code for extra security, verify the request now.

Unveil Code

Developer:
Redirect the user to a landing page where you display the voucher code (remember to switch the voucher code if there are multiple discount options and you used the custom parameters).

Note:
For a better UX, you could include an e-mail form on the landing page so that the user can e-mail the voucher to him-/herself. In addition, you could redirect the user to the checkout page and auto-fill the voucher code into the voucher field using JS.

This integration method uses custom parameters and API. Therefore, only Business accounts will be able to use this embed method. Some of the steps that we show might be redundant or unnecessary. However, we want to show you a wide variety of ways to integrate campaigns so that you can pick the best method for you.

Campaign Status

Developer:
Check if the campaign is still active. If your campaign has time or date limitations (you can set them when you create a campaign), you can use the API to check what status the campaign is in. Based on that, you can decide what to show the user. For more details on the API, please click here.

Embed Codes

Developer:
If a Pay with a Tweet campaign has not yet been created, please click here and follow the steps for creating a campaign. Once the campaign has been created, you will be directed to the embed page. There, you will have a choice between two embed methods. In this scenario you will be using custom parameters and therefore must use the JS embed codes.

Your Website

User:
A User enters your website and is offered a voucher for a 30% discount via Pay with a Tweet. The user clicks the Pay with a Tweet button.

Set Parameters (requires Embed-Code)

Developer:
Pass custom parameters to the JS embed code with any information you might need to trigger the right download. For example, if you want to differentiate between different discounts based on user segments or shopping basket size, you could pass that information to us via custom parameters.

Note:
For extra security, one of the custom parameters could be a user-specific or unique code that is later used to check whether the user has simply copied the access URL or has actually gone through the whole process. For more information about the JS embed codes, custom parameters and JS events, please click here.

Sharing Process

User:
The user enters the three-step sharing process. After a successful share the “Access” button will appear (you can customize the text to something else e.g. “Shop Now” or “Get Voucher” as part of our white-label settings).

Request Access

User:
The user clicks on the access button.

Verify Post

Developer:
Use the API to verify that this user has actually shared.

Receiving Parameters (requires Embed-Code)

User:
Read the custom parameter, which you set in Step 3. If you assigned an user-specific parameter or an unique code for extra security, verify the request now.

Check Validity

Developer:
Use the API to check whether the user has already used this campaign to receiver a voucher on a previous occasion. If not, trigger the landing page that shows the voucher.

Unveil Code

Developer:
Redirect the user to a landing page where you display the voucher code (remember to switch the voucher code if there are multiple discount options and you used the custom parameters).

Note:
For a better UX, you could include an e-mail form on the landing page so that the user can e-mail the voucher to him-/herself. In addition, you could redirect the user to the checkout page and auto-fill the voucher code into the voucher field using JS.

Mark as Redeemed

Developer:
Once the User has actually used the voucher code, mark him as redeemed for this campaign

JavaScript-Events

Reacting to User Actions in the Sharing-Process

If you would like to do something different than just let the user access a certain URL, when he has posted, you can use our JavaScript-Events. On the page, where the ‘Pay with a Tweet’-Button is embeded you can react to certain events while the user is posting. The dispatched event contains information about the specific user actions, so that you can react to them on your page. Parameters are available with a Business membership.

Possible Use-Cases:

Applying a coupon-code after succesfully sharing.

Starting to play a music-video when the user has posted.

Telling the user to finish the sharing process, if he comes back to your site without having done so.

Events

Sharing-Started

Event-Type

pay-with-a-tweet:sharingStarted

This will be fired once the user has clicked the ‘Pay with a Tweet’-Button and the sharing popup has successfully opened.

Event-Attributes

event.buttonUniqueCode

Contains unique ID of the campaign, which was clicked on. If you only have one ‘Pay with a Tweet’ campaign on your page: This is probably your campaigns unique ID.

Sharing-Successful

Event-Type

pay-with-a-tweet:sharingSuccessful

This is fired once we have successfully varified a user's post. Meaning he can see the final page of the sharing process, which cointains the 'access link'. This event is also dispatched if a user clicks on a campaign that he has already succesffuly shared with, using the same network as before.

Event-Attributes

event.buttonUniqueCode

Contains the campaign`s unique ID, for which the sharing occured.

event.provider

The provider that the user used to share. It can contain the following values: facebook, twitter, gplus, vkontakte, xing, linkedin.

event.pwatUid

A Unique ID for a user that is sharing. It identifies him for a certain provider over several shares. Meaning, if a certain Facebook user shares again for any of your campaigns, this ID will be the same as for the previous share. If he uses Twitter this ID will change. Click here to find out more about the Unique ID.

event.postPaymentId

A unique ID for the post that this ‘Pay with a Tweet’ Process relates to. Useful for finding this post later via our _API_. If the user shares again this ID will also not change.

Sharing-Failure

Event-Type

pay-with-a-tweet:sharingFailure

This will be fired when an error occurs during the posting-process that does not let the user continue.

Debugging

Every event that ‘Pay with a Tweet’ hands out to your website should be visible through the JavaScript-Console of your browser.

Example

[Pay With A Tweet] Dispatching Event:startedSharing

Parameters

The ‘Pay with a Tweet’ parameters identify users and allow you to create dynamic access URLs (the links, which users click on once they have shared). For sample cases in which parameters are used as part of the campaign integration please click here. Parameters are available with a Business membership.

User Identification

Every ‘Pay with a Tweet’ user (person who shares) is given a unique ID, with which they can be identified. Use the unique ID to have a secure ‘Pay with a Tweet’ campaign and an extra source of information. For example, if you have multiple campaigns at once or in seqeuence could see if the same person has accessed multiple campaigns. You could also prohibit a user from using the same ‘Pay with a Tweet’ campaign again. For technicial details please look below.

Custom Parameters & Dynamic Access URLs

Provide user specific rewards through the use of custom parameters. Custom parameters can be used to tell us a wide variety of information that we hand over to you once the user shared your post. For example you could tell us the content of their shopping basket so that you can calculate the amount of discount that the user should get once they have shared. Alternatively, if you are a game developer you could tell us the character name of the user and what realm/server they are located on.

Custom parameters are also an alternative way to integrate security measures without having to use our API. Pass onetime parameters to us that you can varify and thereby gurantee that the user has gone through the whole sharing proccess. Alternativly you could feed a list of unique voucher codes as parameters, which you can then mark as redeemed in your system.

With custom parameters there really is nothing you cannot do with ‘Pay with a Tweet’. To find out how to use custom parameters please look below and also check out developer guide here.

Unique User Identifiers

The ‘Pay with a Tweet’ user ID is part of every access request and is attached to the access URL, which the user clicks on once he has shared. Here is an example of an access URL without parameters:

http://www.abc.de/

The parameter is simply:

?pwat_uid=1111&dnt=true

This is an example of the access URL from before with the ‘Pay with a Tweet’ User ID attached:

http://www.abc.de/?pwat_uid=1111&dnt=true

Custom Parameters & Dynamic Access URLs

To pass parameters such as; account name, character name, game world/realm, shoping basket, IP address or anything else, please do the following:

1. Embed Snippet

Outside of the embed code, insert the following code (we inserted example parameters):

Details about the post-payment that were found. See above for the data-explanation.

Marking Post-Payments as 'redeemed'

You can mark post-payments as 'redeemed' via the API by giving their unique-ID on Pay With A Tweet. This can be useful if you want to note that a certain user has received its download on your end. Under normal circumstances a PWAT-UID can only post once for a campaign.