GuidesAPI ReferenceChange LogsRelease Notes
Guides

Create a target for your campaigns

Suggest Edits

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

A 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.

  1. Make a POST API request to get a session URL for uploading your CustomerSet asset to Google Cloud Storage.
  2. 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

With 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

Create an audience_target object

You 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

To 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