Swrve’s background update campaigns use a silent notification to update your app content in the background and, if applicable, add a badge icon to notify the user about the app update. Background updates are available in our consolidated campaign flow as a separate campaign channel. You have the option to add your payload content and launch the campaign directly from Swrve or trigger it externally through our Push API.

Prerequisites

To send background updates to your app, your development team must implement silent or background notifications when integrating the Swrve SDK. For more details, see the relevant platform guide.

• Android
• iOS
• Unity
• Cordova

Create a background update campaign

The first steps for setting up a background update campaign are the same as other channels, with a few extra actions.

1. To create a new campaign from your Campaigns center, select Create campaign.
2. On the Choose your marketing channel screen, select Background update.
3. Under Choose update type, select Scheduled or Via API.
4. Depending on the type of update you selected, under Choose platform, select the platforms you want to send the update to:
   • Scheduled – To send the campaign to all platforms, select All. To create a platform-specific campaign, select the individual platform(s).
   • Via API – Select the required platform.
5. To continue to the Campaign overview screen, select Continue.
6. Enter the Campaign name, Description, and Tags, then select Save to go to the campaign builder.

The blocks on the campaign screen guide you through building your campaign, but you can complete them in any order.

This article mainly covers how to add campaign content, test, and launch your background update campaign. To learn how create your target audience and schedule a the campaign, see the following:

• Targeting campaign audiences
• Scheduling your campaigns

API-triggered campaigns don’t require a target audience or schedule, since they’re triggered by an external system.

Add campaign content

Since the purpose of a background update campaign is to silently wake up the app and update it when it’s running in the background, the content of the campaign consists of a payload, or key-value pairs, that tells the app what content it needs to download.

For API-triggered campaigns, adding content is optional. If the API call includes custom parameters, it overwrites the default content. Note: API campaigns do not include the option to add multiple languages or variants.

1. On the Content block, select edit .
2. In the Custom properties section, you have the option to add individual key/value pairs or to nest multiple key/values under a group name in the JSON payload. Select Add Group + or Add key/value + as required.
3. Depending on your selection in step 2, enter the group name and key/value pair in the Key and Value boxes. To add another key/value pair, select Key/value + or Add key/value +, and then enter the additional key/value pairs as required.
4. After you’ve entered your key/values, select Confirm. The Payload Preview displays a JSON sample of the values you entered.
5. To notify users an update is available by displaying a badge on the app icon, select App icon badge. If selected, a badge containing “1” is displayed and disappears once the user opens the app.

Localizing and A/B testing your content

One of the most exciting features of our streamlined campaign flow is the ability to localize and A/B test your campaign content within a single, unified campaign. Use the Languages and Variant tabs to create localized versions of your content or create variations of your content to test for best conversion.

For more information on how to localize and A/B test your campaign content, see Localizing and A/B testing campaign content.

Testing your campaign

Because background updates don’t display a visible notification, the expected outcome of testing the campaign depends on how your development team has configured your app to handle silent notifications. If you selected the option to display a badge on the app icon, the badge will appear and confirm the test message was successful. To test the campaign on a physical device, first ensure your device is set up on the QA Devices screen.

Testing scheduled campaigns

If your campaign includes multiple languages and variants, select the language or variant you want to test, and then in the header bar, select Test. Select your device from the list and then select Send.

Testing API campaigns

1. On the Content screen or API block, select Test.
2. In the Send test message window, select your device from the list.
3. The window displays sample cURL and HTTP POST commands with the campaign-specific API key and your user ID.
   
   Select Copy to clipboard and edit the JSON payload as required.
4. To send the test background update to the device, run the cURL command from a command-line tool (for example, Command shell on Windows or Terminal on Mac) or copy the HTTP POST command to a REST client service like Insomnia or Postman (remembering to use POST, not GET).

Launching the campaign

How you launch the campaign depends on the campaign type.

Scheduled campaigns

If you have no further changes to your campaign, on the campaign build screen, select Launch or Schedule campaign.

Via API

To make an API campaign active, on the Campaign builder, select Activate campaign.

Once the campaign is active, use the campaign-specific Push API Key and URL displayed on the API block to trigger background updates to individual users, either via webhooks from a third-party system or using your own custom code. For more information on the API call method, URL parameter, expected responses, and possible error codes, see the Swrve push API guide.

Viewing campaign results

Once a campaign is active there are two options for viewing the campaign details and results:

• High-level overview – In the Campaigns center, the campaign card displays the total audience for the campaign. To expand the card and view campaign details, select View metrics . Note, background update campaigns do not track default or custom metrics, so the expanded view only shows the campaign details.
• Detailed report – On the builder page for a specific campaign, to view the detailed campaign report, select View Report.

Understanding your campaign report

The Campaign Report screen displays campaign details and channel-based metrics for your background update campaign. It also displays technical details relating to sent results and possible failure reasons.

Campaign details

The report header displays general campaign information:

• Campaign name: The name given to the campaign.
• Channel: The campaign delivery channel.
• Campaign status: The current status of the campaign. For more information about the different campaign states, see Managing your campaigns.
• Created on: The date the campaign was created.
• Sent: The date and time the campaign was sent if a one-time campaign, or last sent if a recurring campaign.

Overview

The Overview section displays the total Audience to which the campaign was sent. Note, this number may be slightly different from your targeted audience due to factors like app uninstalls or send failures. The percentage of your active user base that the audience represents is displayed below the audience figure.

For campaigns sent Via API, the Audience represents the total number of users who have been sent the update, as triggered by the API call.

Campaign results

The Campaign results section displays the following details about the sent and delivery results of your campaign, depending on the type of campaign—Scheduled (one time and recurring) or Via API.

Scheduled campaigns

• N updates were successfully sent – the number of user devices that qualified for the campaign and were processed by Swrve’s campaign batch job.
• N devices were not updated due to app uninstalls – the number of devices that were not sent the update because the app was uninstalled prior to the update.
• N updates failed to send – the number of device tokens for which an error occurred in the campaign batch job, preventing them from being sent to Apple or Google.
• Last update was sent at [date and time] –  the date and time of the last update that was sent for this campaign.
• N devices were targeted –  the number of user devices that qualified for the update (that is, the number of devices with a device token for the platform of your app). This number will more closely reflect your original targeted audience.
• N devices were not sent an update due to absence of required user property, where no default value was specified – the number of devices that could not be sent a personalized update, since the content included a user property reference with no fallback option, and the user did not have a value set for that user property.
• N batches failed – background update campaigns are sent in batches of 10,000 users at a time. If something goes wrong when sending a batch and the entire batch fails, displays the number of failed batches.
• N messages were rejected immediately on platform [platform name] – the number of device tokens immediately rejected by Apple or Google (due to token invalidity, for example). To view the error message returned by Apple or Google for each rejected device token, select show causes of rejection.

Campaigns triggered via API

The Campaign results for updates triggered via API include a few additional items. For detailed information about failure reasons listed below, see the Push API guide.

• There were N Push API requests: The total number of attempted calls to the Swrve Push API.
• N requests failed due to rate-limiting: The number of API requests that could not be sent due to the app sending too many requests per second and exceeding Swrve’s API rate limits.
• N requests failed due to message text being too large: The number of API requests that could not be sent due to the message text exceeding the size limit of 4 KB.
• N requests failed due to a missing message: The number of API requests that could not be sent due to the message not including body text.
• N requests failed due to no push token being registered for that user: The number of API requests that could not be sent due to no push device token existing for the user ID. This might be because the user hasn’t been prompted to allow silent notifications or they opted out of receiving silent notifications from your app.
• N requests failed due to unknown external_user_id: The number of API requests that could not be sent due to Swrve not recognizing the external user ID. Check that the ID you’ve provided is correct.
• N requests failed due to other reasons: The number of API requests that could not be sent due to other reasons. For a list of error codes you might receive when using the Push/Background update API, see the Swrve Push API guide.
• N updates were successfully sent: The number of user devices that qualified for the update and were processed by Swrve’s background update batch job.
• N devices were not updated to app uninstalls: The number of devices that were not sent the background update because the app was uninstalled prior to the update.
• N updates failed to send: The number of device tokens for which an error occurred in the background update batch job, preventing them from being sent to Apple or Google.
• Last update was sent at [date and time]: The date and time of the last background update that was sent for this campaign.

Next steps

• Manage your campaigns from the Swrve Campaign center. For more information, see Managing your campaigns.
• If you’re triggering background updates via the Swrve push API from a marketing cloud campaign, review how to configure the linked push notification campaign in Salesforce Journey Builder or Oracle Responsys Program.