Skip to main content

Snapchat Integration

Amanda Cross
Updated

When you run ads on Snapchat, people can click them and visit your landing page. From there, they call your Ringba number and you convert the call. The Ringba-Snapchat integration lets you push data about conversions that happened in Ringba back to your Snapchat account using the Snapchat conversion API. Then you can use the analytics tools in Snapchat to evaluate your ads.

Tip: Read more about the Snapchat Conversions API on their developer portal.

This article contains a step-by-step guide on how to set up and track your Ringba calls with Snapchat. This article contains the following sections:

Requirements

Before you get started, you must have the following items:

  • A Snapchat for Business account
  • A Ringba number pool running on the landing page where you want to track calls
  • JS nodes enabled in your account
    Note: The JS node is included in your subscription but is not available by default. Contact Ringba support to enable JS node for your Ringba account.

Important: This integration is not compatible with RTB campaigns.

Flow Overview

This is a brief overview of the solution flow, from the Ringba side and the Snapchat side:

  • A Snapchat user sees your ad on Snapchat and taps it.
  • Snapchat adds user attributes to the URL you configured the ad to point to. The URL resolves to the landing page with your number pool.
  • The number pool code keeps the user data from Snapchat, plus tracks the user's landing page activity.
  • The user calls the number on the landing page.
  • Ringba accepts the call and gets the user data using the number pool. Ringba routes the call to a target.
  • When the call is complete/converted, the pixel you set up in Ringba sends the conversion data to Snapchat.
  • Snapchat receives the data and shows it in your analytics.
  • You use the insight you gain from your Snapchat analytics to optimize your ads.

Setup Guide

This following procedures cover the steps you need to complete in Snapchat and Ringba to set up the integration.

In Snapchat

You complete the first part of the integration configuration in Snapchat.

Create an API token in Snapchat

The Snapchat API requires a token. You include the token in your API calls so Snapchat can match the call to the correct account and authenticate that the code has permission to make changes. 

Use the following steps:

  1. In your Snapchat for Business account, click the menu in the upper left corner and choose Business Dashboard from the menu that appears.
    snapchat_business_dashboard_nav.png
    The Business Dashboard appears.
  2. Click Business Details from the navigation menu.
    snapchat_business_details_nav.png
    The Business Details screen appears.
  3. Scroll down to the Conversions API Tokens section and click the Generate Token button.
    snapchat_generate_token_button.png
    Snapchat generates a new API token. You will use this token later in this procedure.
  4. Click the copy icon to copy the API token to your dashboard. You can paste the token in a secure location to use later.

Create a pixel in Snapchat

You create a pixel in Snapchat to collect information from your landing page.

Use the following steps to get started. For further details, see the Snapchat Business Help Center:

  1. In your Snapchat for Business account, click the menu in the upper left corner and choose Pixels from the menu that appears.
    snapchat_pixels_nav.png
    The Pixels dashboard appears.
  2. Click the Create Pixel button.
    snapchat_create_pixel_button.png
    The Create a Pixel window appears.
  3. Enter a name and click the Create button.
    snapchat_create_pixel_window.png
    The window appears.
  4. Connect the pixel to a Snapchat Ad Account, then click the Set up Pixel button.
    snapchat_pixel_detail_page.png
    The Set Up Web Events window appears.
  5. Click Pixel Code.
    snapchat_pixel_set_up_web_events_window.png
    The window disappears and the Event Setup Method window appears in its place.
  6. You can click either option if you have coding skills. If not, you should choose Pixel Setup Tool.
    snapchat_pixel_event_setup_method_window.png
  7. Complete the steps Snapchat presents to add the required pixel code to your landing page. 

Configure an event source in Snapchat

You configure an event source in Snapchat so it has an event to connect analytics to. 

Use the following steps:

  1. In your Snapchat for Business account, click the menu in the upper left corner and choose Events Manager from the menu that appears.
    snapchat_events_manager_nav.png
    The Events Manager Dashboard appears.
  2. Click the New Events Source button.
    snapchat_new_event_source_button.png
    The Add New Event Source window appears.
  3. Select Web and click Next. 
    snapchat_add_new_event_source.png
    The Create Your Snap Pixel window appears.
  4. Enter a name and click Create.
    snapchat_create_your_snap_pixel.png
    Your snap pixel configuration appears.
  5. Click the Settings tab and scroll down to the Signals Configuration section. Click Set Up Conversion API.
    snapchat_setup_conversions_api.png
    The Set Up Method window appears.
  6. Choose Manual Setup and click Next.
    The Select Funnel Events step appears.
    Note: Snapchat requires certain parameters to match your events to Snapchatters. You can see Snapchat's current documentation here: Structure of the JSON Body. See the note about parameters after this procedure.
  7. Select the events you want to track and click Next.
    snapchat_select_funnel_events.png
    The Add Event and Customer Parameters step appears with an example of the body of the API call the Ringba pixel sends in the Request Payload field.
  8. Choose the events you want to include. (See the note about required parameters after this procedure.) Then scroll down below the Request Payload and Download or Copy Code. Save the code in a safe place until you need it when configuring the Ringba pixel. Then click Next.
    snapchat_add_event_and_customer_parameters.png
    Important: Most of the data you pass to Snapchat must be collected on the landing page. You must include the parameter data in your landing page URL or push them programmatically for your number pool to collect them. For example, you should include the integration parameter with a value of ringba to simplify troubleshooting.  See How to Pass User Data from Your Landing Page into Ringba for more information.

    The Finish Setup screen appears.
  9. Copy the URL from Step 1 on this screen. Save this URL in a safe place until you need it when configuring the Ringba pixel. Then click Finish.
    snapchat_finish_setup.png

Note about required Snapchat parameters

Snapchat requires you to send certain parameters so it can match your events to Snapchatters. You must include at least one of the following parameters options:

  • em (hashed email)
  • ph (hashed phone number)
  • client_ip_address & client_user_agent
  • integration with a value of ringba (This is not required, but strongly advised in case you need to troubleshoot with Snapchat support.) 

Ringba Number pools automatically collect the client IP addresses and the client user agent when available. The tokens that contain this information are the following:

  • user_agent: "[tag:Technology:UserAgentString]"
  • client_ip_address: "[tag:Technology:IPAddress]"

If you elect to use email or phone number, you can send the hashed values to Ringba through your number pool.

You can see Snapchat's current documentation here: Structure of the JSON Body. 
 

In Ringba

This section covers the procedures you complete in Ringba.

Set up your Ringba campaign

You must have a Ringba campaign to manage the calls that come from your Snapchat ads. 

  • If you already have your number pool working on a landing page, then you already have the campaign ready.
  • If not, see Campaigns for more information about setting up campaigns and number pools for information about setting up number pools.

Your campaign needs the pixel and call flow described in the following sections. You can add these to your existing campaign that manages calls from the landing page with your number pool.  

Create a pixel in Ringba

When the call converts, the pixel sends the call data in the format Snapchat requires. 

Use the following steps:

  1. Navigate to Integrations > Pixels and click Create Pixel.
  2. Complete the fields:
    • Name: Enter a name for the pixel.
    • Fire Pixel On: Select Payout or Converted, depending on your preference.
    • URL: Enter the URL you saved when you created an event source in Snapchat. Don't forget to replace the access token with the value you saved in the first procedure.
    • Advanced Options: Toggle on the switch.
    • HTTP Method: Select POST.
    • Content Type: Select application/json.
    • Body: Enter the body you saved when you created an event source in Snapchat. 
      Important: See the note about square brackets after this procedure.
  3. In the Tag Filters section, add a filter that limits the pixel to firing only when the sc_click_id value is present. This filter ensures the pixel fires only for calls generated by the Snapchat ads.
    snapchat_pixel_tag_filter.png
  4. Save the pixel and add it to your campaign.

Note about square brackets in Ringba pixels: 

Snapchat requires some information as arrays, but Ringba recognizes square brackets [] as indicating tags. To be compatible with both systems, any time Snapchat expects an array, you should use double square brackets [[]].

In the following example, you can see double square brackets used to send arrays:

{
    "data": [[
            {
                "event_name": "[tag:User:event_name]",
                "action_source": "website",
                "event_source_url": "[tag:location:cleanUrl]",
                "event_time": 0,
                "user_data": {
                    "em": [["[tag:User:email]"]],
                    "ph": [["[tag:User:phone]"]],
                    "user_agent": "[tag:Technology:UserAgentString]",
                    "client_ip_address": "[tag:Technology:IPAddress]",
                    "sc_click_id": "[tag:User:sc_click_id]",
                    "sc_cookie1": "[tag:User:sc_cookie1]"
                },
                "custom_data": {
                    "event_id": "54ai",
                    "value": "[Call:ConversionAmount]",
                    "currency": "USD",
                    "content_ids": [["[tag:User:content_ids]"]],
                    "content_category": [["[tag:User:content_category]"]],
                    "number_items": [["[tag:User:number_items]"]],
                    "integration":"ringba"
                }
            }
        ]]
}

See Pixels for more information about pixels in Ringba.

Create a call flow with a JS Node

Snapchat requires the call's timestamp to be in UNIX-Epoch format. The simple call flow you add to your campaign converts the call timestamp to the format Snapchat accepts.

snapchat_call_flow.png

See Call Flows with Ringba for step-by-step instructions for creating a call flow and adding it to your campaign. The call flow must include the JS Node and the Dial Node. The JS Node contains the following code snippet:

upsertTag('JS', 'epoch',Math.floor(Date.now() / 1000));

Tip: You can find this and other JavaScript snippets in the JS Node Examples article. 

Send a test call

Try tapping your ad in your Snapchat app, visiting the landing page, and making a call. 

Integration in Action

Now that your landing page is set up with code snippets from both Snapchat and Ringba and Ringba is ready to send call conversion information back to Snapchat, you can create a Snapchat ad campaign to drive traffic to your landing page. 

Snapchat makes creating an ad campaign very easy. They event provide some landing pages for your to choose from! Visit the Snapchat Business Help Center for step-by-step instructions.

Congratulations on completing your integration! You can see your analytics in Snapchat by opening your Event Source and scrolling down to the Event Details section:

snapchat_event_details.png

Related articles