Figure 17: App Center
To get started, create an API Integration with the Marketing Cloud by following the steps below: Navigate to App Center (https://appcenter.exacttarget.com/appcenter).
Click API Integration.
Give the connection a name and description.
Give the connection a package (packages are identifiers that uniquely identify the connection or app in ExactTarget Fuel):
32
Connect your App to an Account
Next, connect your app to an ExactTarget Marketing Cloud account. Your app will access this account when it makes API calls:
The first time you connect an app to an account, you need to select New… from the dropdown menu. App Center saves account references, so if you want to use the same account for future apps, you can select that account from the dropdown menu rather than connecting to a new one.
When you connect an account, you need to tell App Center what type of account it is: • A Production ExactTarget Account is what most developers have access to and use for
development purposes. If you are using a Developer Edition account, you should select Production ExactTarget Account.
• A Sandbox ExactTarget Account exists as a special type of account that some organizations purchase for use in conjunction with a production account for testing.
If you’re not sure which type of account to choose, you should choose Production ExactTarget Account. After you have selected what type of ExactTarget account you want to connect your app to, click the Link to Account button. A new browser window will open and display the ExactTarget Marketing Cloud login screen asking for a username and password.
Note: Don’t confuse the username and password you used to log into App Center with ExactTarget Marketing Cloud credentials—they are different!
Give your App Access to Account Features
Once you log in, you move to the next step of the wizard. In this step, you need to tell App Center what account features your app will need to access to function properly. Your app will receive access to only those account features you specify here. For other app types, like Marketing Cloud apps, the users of your app must have access to these features to use your app in their Marketing Cloud accounts.
Your app will need to create and modify emails, lists, subscribers, and data extensions, as well as send email and retrieve tracking event data, so you will need to give your app access to the following account features and operations:
• Channels – Email Read, Write, Send
• Contacts – List and Subscribers Read, Write
• Data - Data Extensions Read, Write
• Data – Tracking Events Read
Get your App’s OAuth Credentials
After completing this step of the wizard, you will see a summary screen. If everything looks good, click Finish to complete the wizard.
34
Among other things, the summary screen shows you the connected app’s OAuth client credentials, which you will use with the Fuel authentication service to get OAuth tokens that will authenticate your app with other Fuel APIs:
Also note the Courtesy Limit. The Courtesy Limit is a soft capped limit on the number of API calls your app can make. If your app needs to make more than 50,000 API calls per day, it will not be prevented from making them. However, ExactTarget monitors the API usage of each app and can rate limit or throttle apps that are either intentionally or accidentally abusing Marketing Cloud resources.
Note: The connected app’s OAuth client credentials represent pre-authorized access to the account granted through the authorization step of the App Center wizard. You should never expose the client secret on the client side via JavaScript, and you should always take steps to store the client secret securely in your application, as knowledge of the client secret will give anyone full access to the linked account!
You can navigate back to the app summary screen at any time from the App Center main window:
Now your application connects to a Marketing Cloud account, and you received OAuth credentials to that account. Let’s write some code!
You can populate the data extension you created in Going Further with Data Extensions in two ways via ExactTarget Fuel: Using a client library, and using the API directly. In this chapter, we will cover how to do both. You can use this chapter not only as a guide to populating the data extension, but also as a guide on how to use Fuel’s APIs and client libraries.
Using a Client Library
The preferred method of using ExactTarget Fuel is via a client library. In our examples, we will use the PHP client library, though you can easily adapt our examples to the other client libraries as they all follow similar patterns and expose the same objects and properties.
To get started, install the PHP client library in a subdirectory of your workspace called sdk. Make sure you install all dependencies as described in the README of the client library.
To configure the client library, you need to add your OAuth credentials from App Center to config.php (the client library contains a template file you can use to create config.php). Note that you can safely include your OAuth credentials in config.php because config.php is hosted server- side and not exposed to the client:
<?php
return array(
‘appsignature’ => ‘none’,
‘clientid’ => ‘YOUR _ CLIENT _ ID _ FROM _ APP _ CENTER’,
‘clientsecret’ => ‘YOUR _ CLIENT _ SECRET _ FROM _ APP _ CENTER’,
‘defaultwsdl’ => ‘https://webservice.exact target.com/etframework.wsdl’
); ?>
Chapter 6:
the Data Extension
In this chapter …• Using a Client Library
36
After the client library is configured, you initialize it by instantiating an ET_Client object:
<?php
require(‘sdk/ET _ Client.php’); $client = new ET _ Client(); ?>
The ET _ Client object is the central object in all Fuel client libraries and performs a number of tasks for you automatically, including acquiring and refreshing OAuth access tokens using the client credentials you specify in config.php.
After initializing the client library, you can add a row to the data extension we created using the following code:
<?php
require(‘sdk/ET _ Client.php’); $client = new ET _ Client();
$deRow = new ET _ DataExtension _ Row(); $deRow->authStub = $client;
// specify the name of the data extension $deRow->CustomerKey = “subscribers”;
// specify the values of the data extension row
$deRow->props = array(“EmailAddress” => “YOUR _ EMAIL _ ADDRESS”, “FirstName” => “YOUR _ FIRST _ NAME”);
$response = $deRow->post(); print _ r($response);
?>
The following steps outline a typical interaction with a Fuel client library object and highlight the patterns common to all Fuel client libraries:
• Instantiate the object you want to interact with (in this case, ET _ DataExtension _ Row). • Supply the ExactTarget Marketing Cloud account context via the authStub property on the object
($deRow->authStub = $client). (In some client libraries, this is automatically handled for you.) • Identify the object you want to interact with, typically via a unique ID or key. In our case,
CustomerKey is the API equivalent of the External Key value we specified in Going Further with Data Extensions when we created the data extension.
• Set the appropriate properties that govern the operation (in this case, you are creating a data extension row with the “EmailAddress” column set to your email address and the “FirstName” column set to your first name).
• Perform a REST-like operation (GET, POST, PATCH, or DELETE) on the object depending on whether you want to retrieve, create, update, or delete it. In the example above, you create a data extension row, so you perform a POST.