Create a target for your campaigns
You have different options to specify a target audience for your campaigns. You can create a list of users to include in or exclude from your campaigns. Alternatively, you can specify a target audience based on a number of different criteria such as country, language, OS type, and more.
Option 1: Create a customer_set
object
customer_set
objectA CustomerSet entity represents a set of customer IDFAs. You can use this entity to include in or exclude from targeting a specific group of users. To create a customer_set
object, you must upload a .csv
file with customer IDFAs to Google Cloud Storage.
Upload a CustomerSet asset to Google Cloud Storage using Moloco Ads API
To upload a CustomerSet asset to Google Cloud Storage, you must do the following.
- Make a POST API request to get a session URL for uploading your CustomerSet asset to Google Cloud Storage.
- Make a PUT API request with the session URL to upload the CustomerSet asset to Google Cloud Storage.
The following example shows you how you can use your command-line interface to make API requests to get a session URL for your CustomerSet asset and upload the CustomerSet asset to storage. To learn more about the parameters you can specify, see Create a new asset upload session.
You must first make a POST API request with the required parameters as in the following example.
$ cat asset.json
{
"asset_kind": "CSV",
"mime_type": "text/csv",
"file_name": "test_customer_set.csv"
}
$ curl -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d "@asset.json" \
"https://api.moloco.cloud/cm/v1/creative-assets?ad_account_id=$AD_ACCOUNT_ID"
{
"asset_url": "$CUSTOMER_SET_ASSET_URL",
"content_upload_url": "$UPLOAD_URL"
}
As in the example, the response includes the asset URL and upload URL. The asset URL, which is the value of the asset_url
property, is the address where your CustomerSet asset is made available after it has been uploaded to Google Cloud Storage. The upload URL, which is the value of the content_upload_url
property, is for uploading the CustomerSet asset file to Google Cloud Storage.
You must make a PUT API request with the upload URL and upload ID to upload the CustomerSet asset file to Google Cloud Storage. You must include in the request $ASSET_PATH
, which is the location the file is saved in (e.g., my-dir/file.jpg). Be sure to append the upload ID returned in the previous POST API request to the upload URL when making the request as in the following example.
$ curl -i -X PUT \
--data-binary "@$ASSET_PATH" \
-H "Content-Type: text/csv" \
-H "Connection: keep-alive" \
"$UPLOAD_URL&upload_id=$UPLOAD_ID"
When you see that HTTP 200 or 201 is returned as the response, the asset file has been successfully uploaded to storage. You can access the file using the asset URL, which you need when creating a customer_set
object.
Tip: Check the integrity of the uploaded file
To check whether the file you have uploaded has been tampered with, you can make a PUT API request as in the following example.
$ curl -i -X PUT \ -H "Content-Length: 0" \ -H "Content-Range: bytes */*" \ "$UPLOAD_URL&upload_id=$UPLOAD_ID" 2>&1 \ | grep "x-goog-hash\|HTTP\|x-goog-stored-content-encoding" HTTP/2 200 x-goog-hash: crc32c=$GOOG_CRC32C x-goog-hash: md5=$GOOG_HASH x-goog-stored-content-encoding: identity
If your local machine has
gsutil
installed, you can verify file integrity by comparing$GOOG_HASH
and$FILE_HASH
as in the following example. If the two values are the same, your file is safe.$ gsutil hash -m $ASSET_PATH Hashes [base64] for $ASSET_PATH: Hash (md5): $FILE_HASH
Create a customer_set
object
customer_set
objectWith your CustomerSet asset file uploaded to Google Cloud Storage, you can create a customer_set
object using the asset URL for the CustomerSet asset file. You must specify either ADIDs for Android or IDFAs for iOS but not both.
The following example shows you how you can use your command-line interface to make an API request to generate a customer_set
object with the request body parameters you have specified as a .json
file. The parameters you have specified for your new customer_set
object are saved to the .json
file and delivered to the Campaign Management API as an HTTP POST request body. For more information about the parameters you can specify, see Create a new customer set.
$ cat customer_set.json
{
"title": "Test CustomerSet",
"description": "Test CustomerSet",
"id_type": "GOOGLE_ADID",
"data_file_path": "$CUSTOMER_SET_ASSET_URL"
}
$ curl -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d "@customer_set.json" \
"https://api.moloco.cloud/cm/v1/customer-sets?ad_account_id=$AD_ACCOUNT_ID"
{
"customer_set": {
"id": "$CUSTOMER_SET_ID",
"title": "Test CustomerSet",
"description": "Test CustomerSet",
"id_type": "GOOGLE_ADID",
"status": "PREPARING",
"data_file_path": "$CUSTOMER_SET_ASSET_URL",
"created_at": "2020-07-01T15:34:43.323228Z",
"updated_at": "2020-07-01T15:34:43.323228Z"
}
}
As in the example, the response includes the CustomerSet ID, which is the value of the id
property in the customer_set
object. For more information about each of the parameters included in the response, see Create a new customer set.
Option 2: Create and use audience_target
objects
audience_target
objectsCreate an audience_target
object
audience_target
objectYou can have your campaigns target specific users based on a number of different criteria using audience_target
objects.
The following example shows you how you can use your command-line interface to make an API request to generate an audience_target
object with the request body parameters you have specified as a .json
file. The parameters you have specified for your new audience_target
object are saved to the .json
file and delivered to the Campaign Management API as an HTTP POST request body.
In this example, we have created an audience_target
object using the CustomerSet ID to include specific users in the target audience. For more information about the parameters you can specify, see Create a new audience target.
$ cat audience_target.json
{
"title": "Test AudienceTarget",
"targeting_condition": {
"custom_audience_set": {
"include_having_all": {
},
"include_having_any": {
"user_lists": [
"$CUSTOMER_SET_ID"
]
},
"exclude_having_all": {
},
"exclude_having_any": {
}
}
}
}
$ curl -X POST
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d "@audience_target.json"
"https://api.moloco.cloud/cm/v1/audience-targets?ad_account_id=$AD_ACCOUNT_ID"
{
"audience_target": {
"id": "$AUDIENCE_TARGET_ID",
"title": "Test AudienceTarget",
"targeting_condition": {
"custom_audience_set": {
"include_having_all": {
},
"include_having_any": {
"user_lists": [
"$CUSTOMER_SET_ID"
]
},
"exclude_having_all": {
},
"exclude_having_any": {
}
}
},
"created_at": "2023-06-12T07:05:03.373925Z",
"updated_at": "2023-06-12T07:05:03.373925Z"
}
}
As in the example, the response includes the AudienceTarget ID, which is the value of the id
property in the audience_target
object. For more information about each of the parameters included in the response, see Create a new audience target.
Add audience_target
objects to an ad_group
object
audience_target
objects to an ad_group
objectTo use one or more audience_target
objects you have created for your campaigns, you must add them to the respective ad_group
objects. An ad_group
object is automatically created for you upon creating a campaign. To learn how to create additional ad_group
objects for a campaign, see Create a new ad group.
The following example shows you how you can use your command-line interface to read in an ad_group
object of your choice and add the audience_target
object(s). You must make a GET API request with the AdGroup ID and Campaign ID to retrieve the ad_group
object of your choice as in the following example.
$ curl -X GET
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
"https://api.moloco.cloud/cm/v1/ad-groups/$AD_GROUP_ID?campaign_id=$CAMPAIGN_ID"
{
"ad_group": {
"id": "$AD_GROUP_ID",
"title": "Test AdGroup",
"campaign_id": "$CAMPAIGN_ID",
"product_id": "$PRODUCT_ID",
"ad_account_id": "$AD_ACCOUNT_ID",
"enabling_state": "ENABLED",
"audience": {},
"capper": {
"imp_interval": {
"amount": "1",
"unit": "HOUR"
}
},
"pricing_model_id": "cloud_v1",
"created_at": "2022-04-15T13:48:14.982772004Z",
"updated_at": "2022-06-16T02:14:01.815339Z"
}
}
After retrieving the ad_group
object of your choice, you must create a .json
file for the ad_group
object and make a PUT API request to add the audience_target
object(s) to the ad_group
object. You must specify the AudienceTarget ID(s) for the shared_audience_target_ids
property as in the following example. For more information about the parameters you can specify, see Update an existing ad group.
$ cat ad_group_updated.json
{
"id": "$AD_GROUP_ID",
"title": "Test AdGroup",
"campaign_id": "$CAMPAIGN_ID",
"product_id": "$PRODUCT_ID",
"ad_account_id": "$AD_ACCOUNT_ID",
"enabling_state": "ENABLED",
"audience": {
"shared_audience_target_ids": [
"$AUDIENCE_TARGET_ID"
]
},
"capper": {
"imp_interval": {
"amount": "1",
"unit": "HOUR"
}
},
"pricing_model_id": "cloud_v1",
"created_at": "2022-04-15T13:48:14.982772004Z",
"updated_at": "2022-06-16T02:14:01.815339Z"
}
$ curl -X PUT
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d "@ad_group_updated.json"
"https://api.moloco.cloud/cm/v1/ad-groups/$AD_GROUP_ID?campaign_id=$CAMPAIGN_ID"
{
"ad_group": {
"id": "$AD_GROUP_ID",
"title": "Test AdGroup",
"campaign_id": "$CAMPAIGN_ID",
"product_id": "$PRODUCT_ID",
"ad_account_id": "$AD_ACCOUNT_ID",
"enabling_state": "ENABLED",
"audience": {
"shared_audience_target_ids": [
"$AUDIENCE_TARGET_ID"
]
},
"capper": {
"imp_interval": {
"amount": "1",
"unit": "HOUR"
}
},
"pricing_model_id": "cloud_v1",
"created_at": "2022-04-15T13:48:14.982772004Z",
"updated_at": "2023-06-12T08:44:44.567463Z"
}
}
Next steps
You can keep track of campaign events (e.g., clicks, impressions, etc.) using log files. To learn how to do so, see Keep track of campaign events.
Updated 1 day ago