This article provides instructions on how you set up a catalog for Snapchat dynamic ads in Smartly.io. If you have an existing catalog you want to use in Smartly.io, see how to connect an existing Snapchat catalog.

For a basic catalog set-up, you do the following:

1. Create a catalog.
2. Add a feed and and define the feed field mappings.

We also recommend that you set up Smartly.io Image Templates, which allow you to add inspiring overlays to your Snapchat dynamic ads, making them more enjoyable and effective.

See more information on feed files and supported formats.

Limitations

• You can have only product feed per catalog. However, you can have multiple catalogs under an Organization.
• We support the Commerce, hotels and flights catalog verticals.

Before you start

Make sure that you have set up a Snapchat Pixel / SDK sending required events for dynamic ads. Check out the Snapchat guide for installing the pixel and the required pixel events.

Check catalog permissions

Before starting to set up a Snapchat catalog in Smartly.io, check that you have the needed user permissions. Catalogs are managed in Snap Business Manager under Assets > Catalogs.

Smartly.io uses Snapchat Business permissions to determine if a user can create or edit a catalog in Smartly.io. For managing catalogs, you need to have one of the following permissions:

• Organization Admin: Allows you to see and manage all the catalogs under Organization.
• Catalog Admin: Allows you to see and manage a specific catalog you are an admin of.

Connect a Snapchat user to manage your Snapchat catalogs

Each Smartly.io user must connect their Snapchat user account in the Snapchat catalog management view. This is so that Smartly.io can see the catalogs the user has access to.

To connect a Snapchat user account for catalog management:

1. In the top navigation bar, click Catalogs > Snapchat Catalogs. When you enter that view for the first time, you'll see a prompt to connect a Snapchat account to manage catalogs.
2. Click Connect Snapchat user. A pop-up window opens for logging in to Snapchat.
3. Enter your Snapchat username and password and click Continue.
   
   
   
   
4. Once you have successfully logged in, you receive a request to share Smartly.io access to your Snapchat user account. The requested information is required for Smartly.io to show to you the Snapchat Organizations and catalogs you have access to, and to determine that you have the ability to create and manage catalogs in the Organization.
   The ability to see Organizations and catalogs within Smartly.io is user-specific and based on the access of individual users. Other users will not be able to see which Organizations and catalogs you have access to.
   Click Continue.
   You should see the message "Your Snapchat user has been connected to Smartly.io".
   
   
   
   
5. Click Close to close the pop-up window.

After closing the pop-up window, you can select a Snapchat Organization in Smartly.io and see the catalogs you have access to.

Reconnect a Snapchat user to manage your Snapchat catalogs

Sometimes the authorisation between the Snapchat user account and Smartly (also know as the user token) can get invalidated, for example due to a password change. If this happens, you might not be able to see any catalogs listed or your authorisation might not be possible to use to update the catalogs. Sometimes you also might need to change the Snapchat user that is associated with your Smartly user account.

To reconnect a Snapchat user:

1. In the top navigation bar, click Your username > My profile.
2. On the right side of the page, under Authentication > Snapchat, click "Connect a Snapchat account for catalog management".
3. A pop-up window opens for logging in to Snapchat similarly to above guidance. Follow the steps 3-5 in above section to finalise the reconnecting of the Snapchat user to you Smartly user account.

Step 1: Create a Snapchat catalog

1. In the top navigation bar, click Catalogs > Snapchat Catalogs.
2. Click Create Catalog. The Snapchat catalog settings page opens.
3. Enter a name for the catalog and select the catalog vertical.
4. Select which pixels and apps you want to use to track the events for this catalog.
   • It is important to select the correct event sources so that the products and audiences are tracked correctly.
5. Click Create.

Step 2: Add a feed to the catalog

After creating a catalog, you're directed to a feed listing view in the newly created catalog. The feed is where the catalog gets the information about your products.

1. Click Add Feed on the right.
2. Enter a name for the feed.
3. In Data source, enter the feed URL.
   • If the feed is hosted on an SFTP server, add the URL in the following format: sftp://username:password@mydomain.com/path/to/file.csv

     Note When added as part of the feed URL, there are cases where Smartly.io is unable to encode some special characters used in the username and password. If you spot any fetching issues, try using only alphanumeric values for the username and password instead or try to URL encode any non-URL-safe characters in the file path. For example, instead of a space, use '%20'. 

4. To define the advanced settings for the feed, click Advanced settings. See details on how to define the settings.
5. Select the default currency for the catalog.
   • The default currency is used to add the required currency information to price fields if the currency is missing from the feed. 
6. Under Feed updates, define an update schedule for the feed.
7. After the feed preview loads, map the fields coming from your data source (Feed fields) into the predefined Catalog fields in the Catalog mapping section.
   • If there are any missing or incorrect mappings, see Manual field mapping for more information on how to modify them.
   • The catalog fields marked with an asterisk (*) are required. Other fields are optional.
   • If your feed already contains additional image fields, Smartly.io will overwrite them with Image Template URLs. If you want to use the additional images, map image URL fields from your feed to extra fields ("extra_1" - "extra_9") in Smartly.io, and use the fields in Image Templates.
   • If you are using Hotel or Flight vertical catalog and have the "image" field in the JSON format (as it is in the Snapchat feed template), you'll need to use the following liquid template to take the first image from the list of images:

     {%- assign images = image | parse_json -%}
     {{- images[0].link -}}

     The additional fields should be mapped into image templates like highlighted above. See FAQ for further possibilities.
8. Once you are happy with the feed settings and field mapping, click Create New Feed.

Once the above steps are completed, the feed is processed according to the schedule defined under Feed updates. When the feed finishes processing, the catalog is ready to use.

The Smartly.io scheduled feed uploads use Snapchat's "replace" logic. This means that products that don't exist in the feed anymore are deleted from the catalog.

Optional: Add Image Templates to the catalog

To make your Snapchat dynamic ads stand out in a creative way, add Image Templates to your catalog in the Image Templates tab. When you use an Image Template in the catalog, you need to also map the catalog fields to the Image Template fields.

Manual field mapping

In Catalog mapping, you can fine-tune the feed content by mapping your data source feed fields to the predefined field names used in Snapchat catalogs. If Smartly.io is not able to automatically map feed fields to catalog product fields, you'll see red warning highlight in the required catalog fields.

Mappings support using dynamic fields, static text, and Liquid templating. To use Liquid templating, select Use Liquid template in the feed field dropdown selector.

As an example of mapping, if your data source contains the product name in the field name, map that to the catalog field title, because that's where Snapchat picks the names of the products.

Preview value shows you a preview of what Snapchat will see as the catalog values. Use the arrows above the column to preview the values for the different products in your feed.

Example: Connect a Google Sheet as a data source

1. You need a CSV link to your Google Sheet. See how to use Google Sheet to import a data source.
2. When you have created the CSV link to your sheet, copy and paste it to the Data source field.
3. Smartly.io now fetches a preview (sample) of your data source. The UI shows a notification below the URL field when the feed sample has been successfully fetched.
4. You can define advanced settings and adjust the catalog mapping, or save the feed configuration.

Tracking parameters

Within the catalog, on the link attribute, you can append URL parameters. This includes click trackers, UTM parameters, or Snap URL macros. These parameters should be included on each link prior to connecting the feed. In the Smartly.io feed configuration, it is also possible to use Liquid markup to construct the tracking parameters on the feed setup.

Snap URL macros are also available for tracking parameters. Available macros are:

• {{campaign.name}} - send the associated campaign's name in the product link
• {{adSet.name}} - send the associated ad set's name in the product link
• {{campaign.id}} - send the associated campaign's ID in the product link
• {{adSet.id}} - send the associated ad set's ID in the product link
• {{ad.id}} - send the associated ad's ID in the product link

URL macros can be added also with Liquid templating, but the Snapchat macro needs to be added inside {% raw %} {% endraw %} tags so that we do not process them before sending to Snapchat.

For example, you can add the campaign ID macro to the end of the link:

{{link}}?utm_campaign={% raw %}{{campaign.id}}{% endraw %}

*Do note that the Snap URL macros can also be directly used in URL Tracking Parameters section during Ad Set-up.

Required fields for App Ads

In order to create ads to promote your mobile app with the catalog, by creating dynamic ads with either App Install or Deep Link attachment, the following fields are required in the feed mapping: 

• Icon_media_url
• Ios_app_nam
• Ios_app_store_id
• Ios_url
• Android_app_name
• Android_package
• Android_url
• Mobile_link

For further information regarding the contents of these fields, please refer to Snapchat Business Help.

Required fields for Location Aware catalogs

Location Aware gives advertisers the opportunity to apply location information to their products in a catalog to increase relevance and accuracy for their Dynamic Ads campaigns. With Location Aware enabled, Snapchat is able to ingest latitude, longitude, and availability radius for each product, and dynamically serve ads to users that meet each product’s location criteria. For further information regarding this, please refer to Snapchat Business Help.

In order to take advantage of this feature, the following fields are required in the feed mapping: 

• address
• availability_radius

Extra fields

Sometimes you need additional fields for data that you want to use with image template or for field transformations with liquid templating, but don't need to send to Snapchat. Or you might already have all the Snapchat custom_label fields in use. In these situations you can use the Smartly extra fields, extra_1 - extra_9. These fields allow you to map whatever data you want to those fields and use them with Image templates and with liquid templates for field transformations. These fields are not send to Snapchat.

Catalog Authentication for feed uploads

To set (or reset) the catalog authentication:

1. Make sure you have the needed permissions to update the catalog.
2. In the top navigation bar, click Catalogs > Snapchat Catalogs.
3. In Organization, select the Snapchat Organization that has the catalog you want to update.
4. On the catalog list, find the catalog that you want to update and open the catalog view by clicking the catalog's name.
5. Click Catalog settings.
6. Click Change to current user. This will make you as the new catalog authoriser, wether the catalog already had an authoriser or not.
7. The Catalog Authentication should now say "Authorized by you". On the next feed upload the authentication of your connected Snapchat user will be used.

Resolving missing image template when creating campaign with catalog

You recently added a new image template to your Snapchat catalog. Now you want to create a new campaign and ad using that template. But when in campaign creation, the image template you added is missing from the list.

When you add a new image template to a catalog, the feed that Smartly.io sends to Snapchat gets a new column, where each row in the feed will have a new link. This link leads to an image that uses the product and image template.  If the image template does not show up for selection, it is usually due to one of the following issues.

• The feed has not been refreshed: After adding a new image template, you need to refresh the catalog, so that Snapchat will be made aware of the new template. When you refresh the catalog, a new version of the feed with the image templates gets sent to snapchat. In turn, Snapchat returns the info that a new image template is now available, and then you can select it in campaign creation. To refresh the feed, go to the catalogs view in Smartly.io, search for your catalog, and select it. In the feed list, press the refresh button at the end of the catalog row. It will take a while, depending on how many rows and image templates there are in your catalog, to process the catalog. You can see from the status column when the feed is ready. After Status says "Up to date", recheck if the image template is available in campaign creation.
• Every row in your feed is invalid: As image templates are represented as new columns in the feed, a common reason to not seeing an image template is because Snapchat has rejected every row from your feed. With no valid rows in feed, there is no information about products with the image template either. This is more of a symptom of a bigger problem, where everything in the feed is rejected by Snapchat, and can't be used for advertising. Common issues for this is that you are missing one of the required field, or you have values in the fields that are not allowed. You can see the status of the feed by going into the catalog view, and checking the status column for the feed. By clicking the feed status (e.g. "Up to Date"), you will see a list of warnings and errors in the feed. While warnings are good to get fixed, they will not block the use of the row. Errors however will make Snapchat discard the rows. The error names tell what the problem is, for example CAT_VALIDATION_ERROR_MISSING_REQUIRED_COLUMN_DESCRIPTION means that it is an error, and that the required column description did not exist. When you know the errors, you should check the feed you send to Smartly.io for any problems (in this case check description exists for all rows) or update the feed field mappings to correct errors.
• Snapchat needs time before image template can be used: Snapchat might require time to ingest particularly big feeds. That is feeds that have a lot of products and a lot of image templates in them. For example if you have 1 million products in your feed and 8 image templates connected to the feed, that's 8 million pictures that Snapchat needs to download, approve and make available for use. In these cases, you have to wait until Snapchat have completed processing before the image template shows up for use. With the biggest feeds, this can take up to hours. It is recommended that you remove any image templates in the catalog that you are not using any longer, to hasten the processing of the feed. Also splitting catalogs into smaller parts would make each part process faster. 

FAQ

Can I add product sets to catalogs in Smartly.io?

Unfortunately Smartly.io doesn't yet support product set management for Snapchat catalogs, but as the catalogs are synced with Snapchat, you can define product sets on Snapchat Business Manager and use them in the campaign creation in Smartly.io.

I can't see any catalogs in the catalog listing view. / I get an error in the catalog listing view.

First make sure you have the needed permissions. You'll need to have either Organization admin rights (gives access to all catalogs under the Organization), or Catalog admin or Catalog Advertiser role to a specific catalog.

It is also possible that the connection between your Snapchat user and your Smartly user has gotten invalidated. Try reconnecting the Snapchat user by following the instructions here.

There is currently also an edge case, that leads to catalogs listing to fail loading. This is when user has Business admin rights, but no Organization admin rights. In these cases, either give Organization admin rights to user or remove the Business admin rights. We are working to solve the issue on supporting this combination of permissions correctly.

I can't see the feed in Snapchat.

This is normal. From Snapchat's point of view, the feed uploads are now "manual uploads" done by Smartly.io.

Can I see feed processing logs?

You can see the overall processing status of the latest processing and upload.

Can I use Liquid templating with Snapchat catalog feeds?

Yes, Snapchat catalog feed mappings support using dynamic fields, static text, and Liquid templating. 

Can I use custom fields (extra fields) in Snapchat catalogs?

Yes, you can use the fields extra_1, extra_2,..., extra_9 similarly to any extra field in Meta catalogs., essentially to add extra information to image templates via feeds or use them as part of liquid templating. These fields are Smartly specific and won't be send to Snapchat. Unfortunately, at the moment you can't update the naming of these fields.

My catalogs are processing for too long, what can I do?

We recommend you to look into the best practices for decreasing feed processing times for large catalogs, which applies to both Facebook and Snapchat catalogs.

What is the size limit of the feed?

While there are no feed size limitations on Smartly.io, you will experience them from Snapchat. Currently Snapchat supports feeds up to 10 gigabytes. The limit is for the file that Snapchat downloads, so with zipped files (which Smartly is using) you can have even bigger feeds.

Also, according to the Snapchat documentation, there s a limit of maximum 10M products in a feed file.

Is there a limit on how many catalogs I can have under an Organization?

Yes, it is possible to have 200 catalogs under an Organization.

I'm receiving an Access Denied error when claiming the feed.

The feed is likely password-protected. You need to enter the access credentials for the feed in the URL field in the following format:

https://username:password@example.com/feed

The feed processing says "Error during upload notification" What is the issue?

+ The further details in the tooltip read "Snapchat::UploadFeedWorker::FailedUpload - Error code: FORBIDDEN, message: FORBIDDEN".

This kind of error is shown when the catalog authorizer doesn't have the required permissions to update the catalog. Please make sure the catalog authorizer has admin access to the catalog. You can update the access of current authorizer or change the authorizer to a user who has the needed permissions to the catalog.

If the above didn't solve the issue, it is also possible that the connection between your Snapchat user and your Smartly user has gotten invalidated. Try reconnecting the Snapchat user by following the instructions here.

Can I get notifications on possible catalog and feed issues?
Yes, please see Catalog feed processing error alerts -article for more details.

How do I use an Amazon S3 based data source?

Enter "s3://" (or the full URL) in the Data source field. After this, you see the additional configuration fields S3 region, AWS role ARN and AWS role external ID.