Swaarm offers a rewards management platform that handles the complexity of integrating rewarded advertising into your mobile app. Instead of building and maintaining reward systems from scratch, you can use the Swaarm APIs to offer users rewards for interacting with apps and websites.
Core Components
Campaign Management Dashboard
Manage rewarded offers from advertisers through a web interface.
The platform connects with all Mobile Measurement Partners (MMPs) through standard integrations, so you don't need custom attribution setups.
Offers API
A GraphQL API that returns personalized offers for your users. Each response includes offer details, reward amounts, completion requirements, and tracking parameters.
The API handles personalization logic server-side based on user behavior and preferences.
Event Tracking
Server-to-server endpoints for tracking user actions throughout the reward flow. The system identifies when users complete required actions and reach reward milestones, handling the verification process automatically.
Analytics & Reporting
Access individual user reward data and aggregated statistics through API endpoints or the web dashboard.
Query reward points earned, completion rates, and campaign performance metrics.
Getting Started
The typical integration involves:
Setting up your demand sources in the Swaarm dashboard
Integrating the offers API to fetch and display rewarded offers
Implementing event tracking verification for user actions
Retrieving reward points balance for users
Setting up demand sources
To set up the advertiser and offers in the Swaarm dashboard, please follow the guides linked below:
Fetching the Rewarded Offers
There are two methods of retrieving the rewarded offers, a simpler more concise one (called Feed API) that uses a GET endpoint and a complex GraphQL API (Main API) that allows for more filtering and data retrieval.
Feed API
To start using the Feed API you need to first create a Publisher account and then retrieve the associated API Key for it. Please follow the guide linked to create a Publisher and their respective API key
A Publisher can either be one of your apps or you can have one per each user in your platform.
NOTE: This API does not share any private per user data and is read-only so it's safe to use one key across all users.
To access the API, issue a GET request to the following URL:
GET https://feed.${DOMAIN}.swaarm-clients.com/feed/v1.3/ads?apiKey=${API_KEY}&limit=100&offset=0&calledByUser=true&userId=12345
The URL parameters that can be used are the following:
apiKey [Mandatory] - the API key of the publisher accessing the offers
calledByUser - true if the request is made from a user device, false otherwise.
When the API is called by the user device, the system will automatically select the best offers based on the user's device, location and past performance.
limit - amount of offers to be retrieved
offset - amount of offers to be skipped
userId - a user id in your preferred format, if passed the system will optimize the offers for this particular user
The output will look as follows:
{
"ads": [
{...},
{...}
],
"publisher": {
"id": "123"
}
}
The ads object will contain a list of offers that can be displayed, here is an example:
{
"id": "123456",
"app_id": "com.example.app",
"name": "Example App",
"description": "Great App to explore, use the following flow to achieve the rewards: <p>Html is possible here</p>",
"eventTypes": [
{
"id": "123",
"name": "Free Trial"
},
{
"id": "124",
"name": "Reach Level 5",
"payout": {
"currency": "USD",
"value": 1
}
}
],
"click_url": "https://${DOMAIN}.trckswrm.com/click?offer_id=456&pub_id=123&user_id=123455",
"impression_url": "https://${DOMAIN}.trckswrm.com/impression?offer_id=456&pub_id=123&user_id=123455",
"kpi": "You need to play at least 5 hours",
"preview_url": "https://play.google.com/store/apps/details?id=com.example.app",
"creative_packs": [
{
"creatives": [
{
"thumbnailUrl": "https://datagon.s3.eu-central-1.amazonaws.com/9999/1234_thumb.png",
"title": "Example Creative",
"url": "https://${DOMAIN}.swaarm-clients.com/objects/9999/12345.png"
}
],
"description": "Here you can find some creatives",
"title": "Example Pack"
}
],
"targeting": {
"allowedDeviceTargeting": {
"os": "ANDROID"
},
"allowedGeoTargeting": {
"cities": [],
"countries": [
"DE",
"NO",
"NL",
"US"
],
"regions": []
},
"disallowedDeviceTargeting": {},
"disallowedGeoTargeting": {
"cities": [],
"regions": []
}
}
}
GraphQL API
The GraphQL API is better suited when more details are needed for the offers or when specific filters need to be applied and when user data needs to be fetched as well. The GraphQL API is also needed for validating the reward events and for fetching reward balances.
The GraphQL API is meant to be consumed inside the app/website using a different
authentication account per user. User needs to be registered beforehand in Swaarm either by the app or by a backend service.
Usage
There are many GraphQL clients designed for each programming language that provide type safety, autocompletion and much more. You can find a list of these GraphQL clients linked. Of course, traditional HTTP requests also work fine.
During development, it's recommended that queries be tried in the API Playground that you can access from your Swaarm Dashboard.
Authentication
To perform queries on the API, one must first login and obtain an access token.
This can be done through the following query:
mutation {
login(input: {username: "user1@swaarm.com", password: "password"}) {
token {
accessToken
}
}
}
In the response, you will find the access token, that will need to be sent in the Authorization header in each further request. A sample token is shown in the response below:
{
"data": {
"login": {
"token": {
"accessToken": "eyJraWQiOiJ0czFsRnNQY0FrdDNDlCWU5tT2c4XC9GWT0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJmODIwN2Y4ZC0xNjNhLTRlMDEtYmI4YS1mNWQzNjM1OTZkODIiLCJldmVudF9pZCI6IjMxNjU0Yzg1LTJhNDYtNGY1Yy1hYmM2LWVkNmM0Y2FhOGQ1MCIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE3NDg5Nzg3NTEsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5ldS1jZW50cmFsLTEuYW1hem9uYXdzLmNvbVwvZXUtY2VudHJhbC0xX0R6U1NWZkw1aiIsImV4cCI6MTc0OTA2NTE1MSwiaWF0IjoxNzQ4OTc4NzUxLCJqdGkiOiI4NzZkNmE1NS1hMTU4LTRkYjUtOTA2MC1lN2RhMzU4ZGI5NjAiLCJjbGllbnRfaWQiOiJlb2RlazFyZmxmODdjNGNiZnQzZTJnNTE3IiwidXNlcm5hbWUiOiJyb2JvdEBzd2Fhcm0uY29tIn0.Uyi4WCz60EYW9jhM9_urEcJamsB1lOy1gqk2XFA9_v-nPPYTSMalonHieUPdvT3QjHn4WhlfXDpc62YTcVuAW3soT-bEbqIvc12j1PC_wFE4szBcB9URLYcYEfqdhxHeiolXukS-_lLjjg1Y8eGP8BEnz5iAWoG-xJ1dNfMpSdH9WH11sEKKZBbGo9hZ08z2pU-pkMjmlJ4WEsxqFuZIjD2MH7jUYV2bI8USBdDwxIvYjH7vY_3LPxdXgoAj2dRbD6wLUFDY5F3jVg6uuoOUfkAEsTumtOVzisKmbK4hXTOiegpLe_7KYOnbhJhL2R4yxVdkSQ"
}
}
}
}
You can then fetch the offer in formation easily using a query as shown below:
query{
partnerPublisher(id:"123"){
id
name
offersV2(first:2, offset:0){
edges{
node{
id
name
previewUrl
trackingLink
impressionTrackingLink
eventTypes{
id
name
}
paidPayout{
theyGet
eventType{
id
name
}
}
creatives{
title
description
creatives{
title
url
thumbnailUrl
}
}
}
}
totalCount
}
}
}
This would return the top offers for the current logged user ("123"), for example:
{
"data": {
"partnerPublisher": {
"id": "220",
"name": "Rewarded Publisher",
"offersV2": {
"edges": [
{
"node": {
"id": "29154",
"name": "Example offer",
"previewUrl": "https://play.google.com/store/apps/details?id=com.example.app",
"trackingLink": "https://${DOMAIN}.trckswrm.com/click?offer_id=29154&pub_id=220",
"impressionTrackingLink": "https://${DOMAIN}.trckswrm.com/impression?offer_id=29154&pub_id=220",
"eventTypes": [
{
"id": null,
"name": "Default"
},
{
"id": "9415",
"name": "Login"
},
{
"id": "9416",
"name": "Register"
},
{
"id": "9417",
"name": "Purchase"
}
],
"paidPayout": {
"theyGet": 2.1,
"eventType": {
"id": "9417",
"name": "Purchase"
}
},
"creatives": [
{
"title": "Example Pack",
"description": "Here you can find some creatives",
"creatives": [
{
"title": "Example Creative",
"url": "https://creatives.${DOMAIN}.swaarm-clients.com/objects/9999/c9360e5f-4294-bee2-2e97785006f8.png",
"thumbnailUrl": "https://datagon.s3.eu-central-1.amazonaws.com/9999/c9360e5f-4294-bee2-2e97785006f8_thumb.png"
}
]
}
]
}
}
],
"totalCount": 1
}
}
}
}
You can find more options for filtering and requesting different fields in the GraphQL Playground in your dashboard.
Once you have the offers, you need to display them in your application together in offerwalls or any other rendering you prefer.
NOTE: If the offer has an impression tracking link, make sure to load it in a 1x1 pixel or call it using your preferred http client.
When the users click on the rewarded offer creative, they should redirected to the trackingLink url. From this point onwards, everything else will be handled by Swaarm.
Implementing event tracking verification for user actions
Many times, once a user has started a rewarded flow, you might want to signal
inside the application that the user has finished the flow (e.g. they reached level 5 in the game they are supposed to play).
To do this, it's quite simple, you need to repeatedly issue the following query:
{
partnerConversionReport(publisherId: "220", start: "2025-01-01T00:00:00", end: "2025-12-31T00:00:00", fields: [POSTBACK_ID], filters:[
{
field: OFFER_ID,
operator: IN,
values: ["29154"]
},
{
field: OFFER_EVENT_ID,
operator: IN,
values: ["9417"]
}
]){
edges{
node{
records{
field
value{
...on StringValue{
value
}
}
}
}
}
}
}
This query is basically looking for a postback from the advertiser for the target
event (for example: Purchase event, or level 5 completed event) to make sure that the user has completed the flow. Once a postback is returned it means the user can be rewarded.
Each offer will have different events that need to be completed, you can find them
in the offer query described above in the eventTypes section.
Retrieving reward points balance for users
Last step is to show the reward points balance for a user inside your app. This can
help the users know how many offers he completed and how much he is owed.
This can be achieved with the following query:
{
partnerRawReport(publisherId: "220", rawQuery: {
timeRange: {start: "2025-01-01T00:00:00", end: "2025-12-31T00:00:00", granularity: ALL},
dimensions:[DATE],
pagination: {limit: 500, offset:0},
sort: {field:PUB_THEY_GET}
metrics:[PUB_PAID_CONVERSIONS, PUB_THEY_GET]
}){
results{
metrics{
name
value
}
}
}
}
The above query will return the amount of rewarded offers completed as well as the amount of points/USD that the user achieved for the current year.
An example result is shown below:
{
"data": {
"partnerRawReport": {
"results": [
{
"metrics": [
{
"name": "PUB_PAID_CONVERSIONS",
"value": "147.00"
},
{
"name": "PUB_THEY_GET",
"value": "718.55"
}
]
}
]
}
}
}
In the above example, the user completed 147 rewarded tasks, and earned 718.55$. The report can be broken down by offer or by time to report more detailed data.
Custom queries
During development, we can implement certain queries for your app to ensure that the needed functionality is achieved. Please ask your Swaarm account manager or partner developer for more information.
Conclusion
With Swaarm you not only have access to a full fledged dashboard to manager your offers and advertiser but also have access to powerful APIs that save you months of work and the need of a complex backend.
We recommend that you explore all the functionality through the dashboard and API Playground and book an onboarding session with our specialists to make sure you have everything that you need.