AMPScript - Salesforce

Explore

AMPScript | Parte 01

AMPScript é uma linguagem de script usada na plataforma Salesforce Marketing Cloud. Ela permite personalizar e automatizar processos de marketing de maneira eficaz e direcionada. Em vez de escrever código detalhado, os profissionais de marketing podem usar AMP

Júlio Cesar Gomes

1. Linguagem

1.1. Sintaxe

Como o AMPscript é um idioma do lado do servidor, o código pode ser incluído em qualquer local em um email, página da web, SMS ou mensagem push. Semelhante a outras linguagens de script, o AMPscript é interpretado e não compilado, o que significa que é interpretado na ordem em que é escrito. Portanto, se você estiver usando o AMPscript para incluir conteúdo personalizado em um email, o código AMPscript precisará ser definido antes ou no ponto em que o conteúdo personalizado deve aparecer.

1.2. Em bloco de AMPscript

O código AMPScript está contido em uma sequência de caracteres que abre e fecha com duas marcas percentuais %% e contém um delimitador de suporte interno [ e ]

%%[

/* Bloco de AMPScript */

var @nome, @idade

set @nome = "Maria"

set @idade = 30

if @idade >= 18 then

outputline("Olá ", @nome, "! Você é maior de idade.")

else

outputline("Olá ", @nome, "! Você é menor de idade.")

endif

]%%

Os blocos AMPscript são usados para definir o código para interpretação, mas não exibem a saída onde o código aparece no email ou na página. Existem algumas exceções a esta regra através do fornecimento de duas funções Saída e OutputLine, que habilitam variável valores a serem emitidos no local em que o bloco de código aparece.

1.3. Em linha de AMPscript

O código AMPScript está contido em uma sequência de caracteres que abre e fecha com duas marcar percentuais %% e contém um delimitador de suporte interno = e =

Olá %%=v(@nome)=%%, hoje é %%=Now()=%%.

O AMPscript embutido fornece um método conveniente de interpretar e executar uma função no conteúdo da mensagem. Diferentemente dos blocos AMPscript, o AMPscript em linha só pode ser usado com uma única função e a saída da função é exibida onde o código AMPscript em linha aparece. No entanto, funções aninhadas são suportadas.

1.4. Sintaxe baseada em tags

Como alternativa à sintaxe do bloco AMPscript, a tag do script HTML também é suportada. Essa sintaxe pode ser benéfica ao desenvolver em SSJS (Server-Side JavaScript) e AMPscript, pois fornece uma sintaxe padronizada para interpretar os dois idiomas de script do lado do servidor.

Os atributos de runat e language adicionais devem ser incluídos na tag de script de abertura para que o código que contém seja interpretado como AMPscript, conforme indicado no exemplo abaixo:

1.5. Funções

Na programação, a função é uma seção nomeada de um programa que usa alguns valores de entrada (ou argumentos) para executar uma tarefa específica e produzir um valor de saída. Enquanto outras linguagens de script oferecem funções definidas pelo usuário (por exemplo, JavaScript), o AMPscript usa uma abordagem declarativa por meio de funções predefinidas, orientadas principalmente para exibir, transformar e armazenar dados e conteúdo de marketing do clientes.

As funções do AMPscript funcionam da mesma maneira que no Microsoft Excel; isto é, os parâmetros são definidos para uma função predefinida, que é interpretada e, por sua vez, retorna um valor. Várias funções do AMPscript são idênticas às funções do Excel - enquanto algumas funções são nomeadas de maneira diferente, elas compartilham os mesmos parâmetros e produzem o mesmo resultado que o Excel.

1.5.1. AMPScript e Excel

Há um total de 15 funções comparáveis entre Excel e AMPscript que aceitam os mesmos parâmetros e emitem o mesmo resultado, conforme indicado na tabela abaixo.

Funções

Funções

CHAR

Char

CONCATENATE

Concat

FIND

IndexOf

IIf

ISBLANK

Empty

LEN

Length

LOWER

Lowercase

MOD

Mod

NOW

Now

PROPER

ProperCase

RANDBETWEEN

Random

SUBSTITUTE

Replace

SUM

Add

TRIM

Trim

UPPER

Uppercase

⁠

1.6. Variáveis

Semelhante a outras linguagens de programação e script, o AMPscript oferece suporte a variáveis . Na programação, as variáveis fornecem um método conveniente de definir uma função ou valor uma vez e, em seguida, reutilizar essa variável referenciando-a no código. Isso é da mesma forma que as classes Cascading Style Sheets (CSS) são definidas uma vez e, em seguida, as propriedades de estilo definidas são aplicadas a um ou mais elementos, incluindo o nome da classe em um atributo de classe. No entanto, as variáveis não apenas permitem que valores fixos (ou

constantes⁠

) sejam definidos uma vez, mas também funções AMPscript e, por sua vez, o valor de saída da variável pode mudar dependendo do contexto para o qual é interpretado.

1.6.1. Convenção de nomes

As variáveis são essencialmente 'contêineres nomeados', onde um nome definido pelo usuário é aplicado a uma entidade definida, seja uma constante ou função. Os nomes de variáveis não diferenciam maiúsculas de minúsculas e podem incluir caracteres ou números, mas não espaços ou vírgulas. Os nomes das variáveis devem começar @ e incluir pelo menos uma outra letra, número ou sublinhado. Você deve considerar a nomeação de variáveis com uma taxonomia legível por humanos que tenha significado ou contexto para outras pessoas, para que seu código seja fácil de interpretar e não exija engenharia reversa para compreender sua finalidade.

Por exemplo, se você estiver definindo uma variável que deriva um valor de pontuação de propensão dos dados do cliente, considere usar um nome como @propensityScore , não @ps. Além disso, pode ser útil aplicar a notação camel case para nomes de variáveis que são compostos por mais de uma palavra colocando as palavras subsequentes em maiúsculas. Por exemplo, uma variável nomeada @preferredContactNumber é mais fácil de ler do que @preferredcontactnumber.

1.6.2. Declarando variáveis

Antes que uma variável possa ser definida , ela deve ser declarada. As variáveis são declaradas com a var palavra-chave, seguida por um ou mais nomes de variáveis delimitados por vírgulas. Por exemplo, se você precisar definir o nome, o sobrenome e a data de expiração da associação de um membro, as variáveis podem ser declaradas como:

var @firstName, @lastName, @membershipExpiryDate

declaração de uma variável adiciona uma entrada a um Dicionário de variáveis interno, usando o nome da variável como chave e null como valor. Se já existir uma entrada para esse nome, o valor da variável será redefinido para null.

NOTA: AMPscript é uma linguagem de tipagem flexível e, como resultado, o interpretador não obriga a declaração de variáveis. No entanto, é uma prática recomendada fazer isso para garantir que o nome da variável seja adicionado ao Dicionário de variáveis.

1.6.3. Variáveis de configurações

Depois que uma variável é declarada, ela pode ser definida. As variáveis são definidas usando uma sintaxe que compreende quatro elementos:

a set palavra-chave

o nome da variável

um único símbolo de igual (=)

uma string de personalização , constante ou função AMPscript (que pode conter funções aninhadas).

Consulte o exemplo abaixo, onde as variáveis são definidas como uma string de personalização ( @firstName), função AMPscript ( @localDate) e constante ( @promotionEndDate):

%%[

var @firstName, @localDate, @promotionEndDate

set @firstName = FirstName

set @localDate = SystemDateToLocalDate(Now())

set @promotionEndDate = '10/15/2018'

]%%

var @firstName, @localDate, @promotionEndDate: Aqui, três variáveis são declaradas: @firstName, @localDate e @promotionEndDate.

set @firstName = FirstName: Essa linha atribui o valor da variável personalizada FirstName à variável @firstName.

set @localDate = SystemDateToLocalDate(Now()): Aqui, a função Now() é usada para obter a data e a hora atuais do sistema no formato GMT (hora padrão). Em seguida, a função SystemDateToLocalDate() é usada para converter essa data e hora para o fuso horário local. O resultado é armazenado na variável @localDate

set @promotionEndDate = '10/15/2018': Aqui, uma data específica, neste caso, '10/15/2018', é atribuída à variável @promotionEndDate. Isso pode indicar a data de término de uma promoção ou evento.

Resumindo, esse código em AMPscript é usado para:

Armazenar o nome do destinatário na variável @firstName.

Obter a data e hora atuais no fuso horário local e armazená-las na variável @localDate.

Definir uma data específica ('10/15/2018') na variável @promotionEndDate.

1.6.4. Escopo

Depois que uma variável é definida, seu escopo é definido globalmente; ou seja, pode ser referenciado posteriormente no código para exibir a saída ou usado em expressões condicionais. No entanto, as variáveis também podem ser alteradas depois de terem sido definidas. Por exemplo, a data de término de uma promoção é definida em um campo em uma extensão de dados enviáveis usando uma string de personalização, mas para clientes específicos, há um requisito para ajustar esse valor posteriormente no código:

%%[

var @promotionEndDate, @memberStatus

set @promotionEndDate = '10/15/2018'

set @memberStatus = status

if @memberStatus == 'gold' then

set @promotionEndDate = '11/15/2018'

endif

]%%

As variáveis também podem ser definidas em si mesmas em uma função; ou seja, se a variável foi declarada anteriormente, ela pode ser usada como argumento para uma função, com base em seu valor anterior. Portanto, o código acima também pode ser expresso como:

%%[

var @promotionEndDate, @memberStatus

set @promotionEndDate = '10/15/2018'

set @memberStatus = status

if @memberStatus == 'gold' then

set @promotionEndDate = DateAdd(@promotionEndDate, 1, 'M')

endif

]%%

Além disso, uma vez que uma variável tenha sido definida, ela pode ser redefinida declarando o valor novamente. No exemplo abaixo, se a data atual for menor que (após) a data de término da associação, um null valor será definido para o status da associação.

%%[

var @membershipEndDate, @memberStatus

set @membershipEndDate = '10/15/2018'

set @memberStatus = status

if @membershipEndDate > Now() then

var @memberStatus

endif

]%%

A única exceção a esta regra de escopo é quando uma variável é usada dentro de um for bloco. Nesse cenário, a variável está bloqueada para modificação dentro do loop do processo .

1.6.5. Ordem de operações

Como outras linguagens de script, o AMPscript é interpretado de cima para baixo, o que significa que as variáveis devem ser declaradas e definidas antes de serem usadas. No entanto, os componentes de e-mail são interpretados na seguinte ordem:

Pré-cabeçalho

corpo HTML

corpo do texto

Linha de assunto

Por exemplo, uma variável pode ser declarada e definida em um corpo HTML (dentro de um bloco AMPscript) e usada em uma linha de assunto:

%%[

var @subjectLine

if AttributeValue('Member Status') == 'VIP' then

set @subjectLine = 'An exclusive offer for VIP members'

else

set @subjectLine = 'A special offer for our members'

endif

]%%

%%=v(@subjectLine)=%%

OBSERVAÇÃO: funções AMPscript aninhadas e variáveis aninhadas não serão processadas em linhas de assunto a partir de 21 de fevereiro de 2023. Consulte este documento de ajuda para obter mais informações sobre essa alteração.

1.6.6. Usando variáveis

As variáveis não são necessárias no AMPscript. É possível obter o mesmo resultado usando apenas funções, declarações condicionais e operadores. No entanto, sem variáveis:

funções e constantes precisariam ser definidas várias vezes, geralmente resultando em mais código e dificultando a manutenção

cada função AMPscript duplicada precisa ser interpretada novamente, resultando em possíveis problemas de desempenho ao enviar e-mails ou renderizar conteúdo.

O exemplo abaixo indica a inclusão de duas variáveis no AMPscript para recuperar um saldo de pontos e exibir um nível de status correspondente.

%%[

var @pointsBalance, @status

set @pointsBalance = Lookup("Points Balance","Balance","MemberId", _subscriberKey)

if @pointsBalance < 100 then

set @status = "bronze"

elseif @pointsBalance > 100 and @pointsBalance < 500 then

set @status = "silver"

else

set @status = "gold"

endif

]%%

You are a valued %%=v(@status)=%% member.

Ao escrever AMPscript, é uma boa prática otimizar seu código por meio da configuração de variáveis para funções comumente usadas.

1.7. Comentário

Os comentários podem ser incluídos nos blocos AMPscript. Eles estão contidos em um par de sintaxe de abertura /*e fechamento */e fornecem a capacidade de incluir uma explicação ou anotação legível para os usuários. Quaisquer comentários são ignorados pelo Marketing Cloud e não serão interpretados. Eles podem ser usados em uma única linha ou percorrer várias linhas.

Exemplo 1

Este é um exemplo de comentário de uma linha:

%%[ /* Este é um exemplo de comentário de uma linha em AMPscript. */

set @variable = "valor"

]%%

Exemplo 2

Aqui está um exemplo de um comentário que atravessa várias linhas:

%%[

Este é um exemplo de um comentário

que se estende por várias linhas em AMPscript.

Pode ser usado para explicar partes mais extensas

do código ou fornecer informações detalhadas.

set @variable = "valor"

]%%

1.8. Function calls

As funções são interpretadas ou 'chamadas' dentro de um bloco AMPscript ou AMPscript embutido, no local onde aparecem na página ou na mensagem. No entanto, as funções não precisam estar contidas no mesmo bloco AMPscript. Por exemplo, ao usar instruções condicionais , a expressão condicional pode abranger vários blocos:

%%[

var @balance

set @balance = Lookup('Points Balance', 'Balance', 'MemberId', _subscriberKey)

]%%

%%[ if @balance < 100 then ]%%

You are a valued bronze member.

%%[ elseif @balance > 100 and @balance < 500 then ]%%

You are a valued silver member.

%%[ else ]%%

You are a valued gold member.

%%[ endif ]%%

Da mesma forma,

os loops de processo⁠

podem (e normalmente o fazem) abranger vários blocos, conforme indicado abaixo.

<h2>Your Order Items</h2>

<ul>

%%[

var @orderId, @rows, @row, @rowCount, @i

set @orderId = AttributeValue("OrderId")

set @rows = LookupRows("Orders","OrderId", @orderId)

set @rowCount = rowcount(@rows)

if @rowCount > 0 then

for @i = 1 to @rowCount do

var @name, @value

set @row = row(@rows, @i)

set @name = field(@row,"Name")

set @value = field(@row,"Value")

]%%

<li>%%=v(@name)=%%, $%%=v(@value)=%%</li>

%%[ next @i ]%%

%%[ else ]%%

<li>No items ordered</li>

%%[ endif ]%%

</ul>

1.9. Constantes

Na programação, uma constante é um valor que nunca muda. No AMPscript, esses valores predefinidos ou codificados são usados para definir um valor fixo para avaliação ou pesquisa. Eles podem ser uma constante, numérica, string ou um valor booleano.

1.9.1. Constantes numéricas

As constantes numéricas consistem em um conjunto de numerais sem aspas. Eles também podem incluir um ponto decimal e podem ser prefixados com um símbolo de menos para indicar valores negativos. Constantes numéricas não podem conter vírgulas, conforme indicado abaixo:

%%[

var @discountAmount

set @discountAmount = -10.50

]%%

1.9.2. Constantes de strings

Valores constantes de string (ou texto) devem usar aspas duplas ou simples, conforme indicado no exemplo aqui:

%%[

var @statusTier

set @statusTier = "Gold"

]%%

Se aparecerem aspas dentro do texto, as constantes de string podem escapar das aspas delimitadoras quando seu tipo de aspas for trocado (para simples ou duplo). Caracteres de aspas alternativas, como aspas inteligentes, não são suportados.

%%[

var @bonusProduct

set @bonusProduct = 'Our "Uber" Umbrella'

]%%

1.9.3. Constantes booleana

Os valores das constantes booleanas devem usar valores trueor falsee não diferenciam maiúsculas de minúsculas, conforme mostrado no exemplo abaixo:

%%[

var @statusTier, @freeShipping

set @statusTier = AttributeValue("Tier Level")

if @statusTier == "Gold" then /* string constant */

set @freeShipping = true /* Boolean constant */

endif

]%%

1.10. Atributos

⁠

Strings de atributos⁠

e outras

strings de personalização⁠

também podem ser usadas com AMPscript. No entanto, neste caso, os delimitadores de porcentagem dupla ( %%) não devem ser incluídos.

Se o atributo incluir um caractere de espaço ou hífen, a string deverá estar entre colchetes quando usada em uma função AMPscript.

No exemplo abaixo, uma extensão de dados enviáveis inclui os campos 'MemberID', 'First Name' e 'Order-Amount':

%%[

var @MemberID, @FirstName, @OrderAmount

/* Suponha que @subscriberKey seja a chave única do assinante que você está segmentando */

set @subscriberKey = AttributeValue("SubscriberKey")

set @lookupKey = "MemberID" /* O campo que você quer usar para buscar os dados na extensão */

/* Faz a pesquisa na extensão de dados */

set @MemberID = Lookup("CustomerDataExtension", "MemberID", "SubscriberKey", @subscriberKey)

set @FirstName = Lookup("CustomerDataExtension", "First Name", "SubscriberKey", @subscriberKey)

set @OrderAmount = Lookup("CustomerDataExtension", "Order-Amount", "SubscriberKey", @subscriberKey)

]%%

MemberID: %%=v(@MemberID)=%%

First Name: %%=v(@FirstName)=%%

Order Amount: %%=v(@OrderAmount)=%%

Neste exemplo, estamos usando a função Lookup para buscar os valores dos campos 'MemberID', 'First Name' e 'Order-Amount' da extensão de dados "CustomerDataExtension" com base no valor da chave única do assinante (@subscriberKey). Em seguida, armazenamos esses valores nas variáveis @MemberID, @FirstName e @OrderAmount para uso posterior no código.

As linhas finais, %%=v(@MemberID)=%%, %%=v(@FirstName)=%% e %%=v(@OrderAmount)=%%, exibem esses valores na saída do email.

1.11. Declarações

A if instrução permite a avaliação condicional de uma ou mais expressões, que, se for avaliada como true, processará o bloco de código dentro dela.

Uma ifdeclaração, no mínimo, deve conter três elementos:

uma if declaração de abertura

uma then instrução precedendo a expressão para avaliação

uma end i fdeclaração de encerramento.

As expressões dentro de uma if instrução podem incluir os seguintes tipos:

Constantes

Variáveis

Atributos

Strings de personalização

Chamadas de função

Exemplo 1

No exemplo a seguir, a @groupvariável será somente setse o valor de @agefor maior ou igual a 18:

%%[

var @age, @group

/* Suponha que @age seja a idade do usuário */

set @age = AttributeValue("Age")

/* Verifica se o valor de @age é maior ou igual a 18 */

if not empty(@age) and @age >= 18 then

set @group = "Adult"

endif

]%%

Age: %%=v(@age)=%%

<br>

Group: %%=v(@group)=%%

Exemplo 2

No exemplo a seguir, se o valor de @agefor maior ou igual a 18, então a @groupvariável será apenas set, adultcaso contrário, será definida como child.

%%[

var @age, @group

/* Suponha que @age seja a idade do usuário */

set @age = AttributeValue("Age")

/* Verifica se o valor de @age é maior ou igual a 18 */

if not empty(@age) and @age >= 18 then

set @group = "Adult"

else

set @group = "Child"

endif

]%%

Age: %%=v(@age)=%%

<br>

Group: %%=v(@group)=%%

Suponha que temos uma variável @age representando a idade do usuário e uma variável @gender representando o gênero. Vamos atribuir um grupo com base nas seguintes regras:

Se a idade for maior ou igual a 18 e o gênero for "Masculino", o grupo será "Adult Male".

Se a idade for maior ou igual a 18 e o gênero for "Feminino", o grupo será "Adult Female".

Se a idade for menor que 18, o grupo será "Child".

Aqui está o exemplo:

%%[

var @age, @gender, @group

/* Suponha que @age e @gender sejam as idades e gêneros dos usuários */

set @age = AttributeValue("Age")

set @gender = AttributeValue("Gender")

/* Verifica a idade e o gênero para definir o grupo */

if not empty(@age) then

if @age >= 18 then

if @gender == "Masculino" then

set @group = "Adult Male"

elseif @gender == "Feminino" then

set @group = "Adult Female"

endif

else

set @group = "Child"

endif

]%%

Age: %%=v(@age)=%%

<br>

Gender: %%=v(@gender)=%%

<br>

Group: %%=v(@group)=%%

1.12. Operadores de comparação

Operadores de comparação são usados para comparar dois valores ou operandos. O resultado da avaliação retornará um resultado booleano. Existem seis operadores de comparação disponíveis no AMPscript.

Os operandos precisam ser do mesmo tipo; por exemplo, string, data, número ou booleano:

Operadores de comparação

Operadores de comparação

Operador

Descição

é igual a

não é igual a

é melhor que

é menos do que

é maior que ou igual a

é menor ou igual a

There are no rows in this table

⁠

Os operandos de string só podem usar operadores ==ou !=para comparação. As comparações de string são avaliadas como não diferenciando maiúsculas de minúsculas, portanto, "GOLD" == "gold"serão avaliadas como true.

Exemplo 1

No exemplo a seguir, Verificando se o valor de uma variável é igual a um número:

%%[

var @score

set @score = AttributeValue("Score")

if not empty(@score) and @score == 100 then

set @result = "Pontuação perfeita!"

else

set @result = "Pontuação não é perfeita."

endif

]%%

Score: %%=v(@score)=%%

<br>

Result: %%=v(@result)=%%

Neste exemplo, estamos usando o operador de comparação == para verificar se o valor da variável @score é igual a 100. Dependendo do resultado da comparação, atribuímos uma mensagem específica à variável @result.

Exemplo 2

No exemplo a seguir, verificando se o valor de uma variável está dentro de um intervalo:

%%[

var @temperature

set @temperature = AttributeValue("Temperature")

if not empty(@temperature) and @temperature > 20 and @temperature <= 30 then

set @weather = "Agradável e quente"

else

set @weather = "Condições diferentes"

endif

]%%

Temperature: %%=v(@temperature)=%%

<br>

Weather: %%=v(@weather)=%%

Neste exemplo, estamos usando os operadores de comparação > (maior que) e <= (menor ou igual a) para verificar se o valor da variável @temperature está dentro do intervalo entre 20 (exclusivo) e 30 (inclusive). Dependendo do resultado da comparação, atribuímos uma descrição do clima à variável @weather.